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machine-oriented mode of PSL, called SYSLISP, to perform word, byte, and 
efficient integer and string operations. PSL is compiled by an enhanced 
version of the Portable LISP Compiler, and currently runs on the DEC-20, 
VAX, and MC68000. 
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Preface 


This Portable LISP implementation would not have been started without the 
effort and inspiration of the original STANDARD LISP reporters (A. 
C. Hearn, J. Marti, M. L. Griss and C. Griss) and the many people who gave 
freely of their advice (often unsolicited!). We especially appreciate the 
comments of A. Norman, H. Stoyan and T. Ager. 


It would not have been completed without the efforts of the many people 
who have” worked arduously on SYSLISP and PSL at various levels: Eric 
Benson, Will Galway, Martin Griss, Bob Kessler, Steve Lowder, Chip Maguire, 
Beryl Morrison, Don Morrison, Bobbie Othmer, Bob Pendleton, and John 
Peterson. 


This document has been worked on by most members of the current Utah 
Symbolic Computation Group. The primary editorial function has been in the 
hands of B. Morrison and M. Griss; major sections have been contributed by 
E. Benson, W. Galway, and D. Morrison. 


This is a preliminary version of the manual, and so may suffer from a 
number of errors and omissions. Please let us know of problems you may 
detect. 


We have also made some stylistic decisions regarding Font to indicate 
semantic classification, Case to make symbolS more readable, and RLISP 
syntax for code examples. We would appreciate comments on these choices. 
Please feel free to comment on Chapter order also. 


Report bugs, errors and mis-features by sending MAIL to PSL-BUGSGUtah-20; 
alternatively, send a message to Benson and Griss from within PSL by 
calling the Bug function, BUG(); in RLISP. 


Permission is given to copy this manual for internal use with the PSL 
system. i 
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CHAPTER 1 
INTRODUCTION 


1. Opening Remarks 1 
.2. Scope of the Manual 1 
1.2.1. Typographic Conventions within the Manual 1. 
1.2.2. The Organization of the Manual 1 
.3. The Development of Portable Standard LISP 1 
4, Brief Overview of PSL as a Portable Modern LISP 1 


1.1. Opening Remarks 


Although the programming language LISP was first formulated in 
1960 [McCarthy 73], a widely accepted standard has never appeared. Various 
dialects of LISP have been produced (e.g. MACLISP, Inter LISP, Franz LISP, 
Common LISP, LISP 1.6, UCI LISP, UT LISP, LISP 360), in some cases several 
on the same machine! Consequently, a user often faces considerable 
difficulty in moving programs from one system to another. In addition, it 
is difficult to write and use' programs which depend on the structure of the 
Source code such as translators, editors and cross-reference programs. 


“In order to enhance the portability of the REDUCE Computer Algebra 
system [Hearn 73] and related tools (such as Meta Compilers, Editors, 
etc.), a reasonable dialect called Standard LISP was defined [Marti 79] and 
implemented on a number of machines by either mapping to an existing LISP 
(with slight interpreter modifications) or by implementing a totally new 
LISP. Machines now supporting Standard LISP include the DEC-10/DEC-20, IBM 
360/370, CDC 6600/7600, CRAY-1, Univac 1108, Burroughs B1800, B6500 and 
B6700. 


This document describes PSL (a Portable Standard LISP), a portable, 
efficient, "modern" LISP for a variety of machines. The interpreter is 
written entirely in itself, using a machine-oriented mode (i.e. a 
LISP-based systems implementation language) called SYSLISP [Benson 81]. 
Current implementations compile SYSLISP to assembly language on a DEC 
System 20 and on a VAX-11/750; an extended addressing DEC-20 version is 
planned. Implementations are under way for Motorola 68000-based personal 
machines. PSL is upward-compatible with Standard LISP; we have used 
function definitions as given in the Standard LISP Report [Marti 79] as 
much as possible, and have only deviated if LISP programming experience we 
have had since writing that Report made a change seem desirable. In most 
cases, Standard LISP did not commit itself to specific implementation 
details (since it was to be compatible with a portion of "most" LISPs). 
PSL is much more specific, and users can take advantage of these details. 
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The goals of PSL implementations include: 


a. Providing a library of LISP implementation modules that can be 
used to implement a variety of LISP-like systems, including 
Mini-LISPs embedded in other language systems (such as existing 
PASCAL or ADA applications). 


b. Effectively supporting the REDUCE algebra system on a number of 
machines, and permitting LISP-coded algebra modules extracted 
from or modeled upon REDUCE to be included in applications such 
as CAI and CAGD. 


C. Providing the same, uniform, modern LISP programming environment 
on all of the machines that we use (DEC-20, VAX/750, and 68000 
based personal machine) of the power of Franz LISP, UCI LISP or 
MACLISP, with some extensions and enhancements motivated by the 
work on NIL, Spice LISP and the LISP Machine (now being combined 
into a new Common LISP [Steele 81]). 


d. Studying the utility of a LISP-based systems language for other 
applications (such as CAGD or VLSI) in which SYSLISP code 
provides efficiency comparable to that of C or BCPL, yet enjoys 
an interactive program development and debugging environment 
with the full power of LISP. 


1.2. Scope of the Manual 


While we have attempted to make this manual comprehensive, it is not 
intended for use as a LISP primer. Some minimal prior exposure to LISP 
will prove very helpful. A selection of LISP Primers is listed in the 
bibliography in Chapter 24; see for example [Allen 79, Charniak 
80, Weissman 67, Winston 81]. The manual is intended to describe the 
syntax and the semantics of PSL. It is also intended to be an 
implementation description, and it specifies many of the details left out 
of the Standard LISP Report [Marti 79]. 


1.2.1. Typographic Conventions within the Manual 

Each function is provided with a prototypical header line. Each formal 
parameter is given a name and followed by its allowed type. The names of 
classes referred to in the definition are printed like this, and parameter 
names are printed LIKE THIS. The name of the function looks Like This. If 
a parameter type is not commonly used, it may be a specific set enclosed in 
brackets {...}. For example: 


PutD(FNAME:id, TYPE:ftype, BODY:{lambda, code-pointer)): FNAME:id expr 


a 


J 
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PutD is a function with three parameters. The parameter FNAME is an id 
which is the name of the function being defined. TYPE is the type of 
function being defined and BODY is a lambda expression or a code-pointer. 
PutD returns the name of the function being defined. Some functions are 
compiled open; these have a note saying "open-compiled" . next to the 
function type. 


Functions which accept formal parameter lists of arbitrary length have 
the type class and parameter enclosed in square brackets indicating that 
zero or more occurrences of that argument are permitted. For example: 


And((U:form]): extra-boolean 


And is a function which accepts zero or more arguments which may be any 
forms. 


In some cases, some code is given in the function definition. The code 
given is not necessarily the same as that in the source files; it is given 
to clarify the semantics of the function. 


Some components of PSL have not yet been fully implemented. Some things 
which have not yet been fully implemented are documented here anyway for 
the sake of completeness. We flag the cases not yet implemented by the 
words: 


[not implemented yet] 


1.2.2. The Organization of the Manual 

The manual is arranged in separate Chapters, which are meant to be 
Self-contained units. Each begins with a small table of contents, serving 
as a summary of constructs. It will also aid in the skimming of topics 
online. 


The rest of this Chapter discusses organization of the manual, the 
history of the development of PSL, and PSL as a modern portable LISP. 


Chapter 2 is particularly useful in first using PSL. It begins with 
directions for starting PSL and getting help. Among other topics presented 
briefly are errors, a discussion of some of the consequences of PSL being 
both a compiled and an interpreted language, function types, and flags and 
globals. It would be worth while to glance at those Sections. PSL treats 
the parameters for various function types rather differently from a number 
of other dialects, and the serious user should definitely become familiar 
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with this information. 


While most LISP implementations use only a fully parenthesized syntax, 
PSL gives the user the option of using an ALGOL-like (or  PASCAL-like) 
syntax (RLISP), which many users find more pleasant. Chapter 3 describes 
the syntax of RLISP. Most of the examples and definitions in this manual 
are presented in that syntax. 


[??? Should we use only Lisp-like through-out ??7] 


Chapter 4 describes the data types used in PSL. It includes functions 
useful for testing equality and for changing data types, and predicates 
useful with data types. 


The next seven Chapters describe in detail the basic functions provided 
by PSL. 


Chapters 5, 6, 7, and 8 describe functions for manipulating the basic 
data structures of LISP: numbers, ids, lists, and strings and vectors. As 
virtually every LISP program uses integers, identifiers, and lists 
extensively, these three Chapters (5, 6 and 7) should be included in an 
overview. As vectors and strings are used less extensively, Chapter 8 may 
be skipped on a first reading. 


Chapter 9 and, to some extent, Chapter 4 describe the basic functions 
used to drive a computation. The reader wanting an overview of PSL should 
certainly read these two. 


Chapter 10 describes functions useful in function definition and the idea 
of variable binding. The novice LISP user should definitely read this 
information before proceeding to the rest of the manual. Also described in 
this Section is context-switching in the form of the funarg and closures. 


Chapter 11 describes functions associated with the interpreter. It 
includes functions having to do with evaluation (Eval and Apply.) 


Chapter 12 describes the global variables which control the operation of 
PSL. 


Chapter 13 describes the I/O facilities. Most LISP programs are written 
with almost no sophisticated I/O, so this may be skimmed on a first 
reading. The Section dealing with input deals extensively with customizing 
the scanner and reader, which is only of interest to the sophisticated 
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Chapter 14 presents information about the user interface for PSL. It 
includes some generally useful information on running the system. 


Chapter 15 discusses error handling. Much of the information is of 
interest primarily to the sophisticated user. However, LISP provides a 
convenient interactive facility for correcting certain errors which may be 
of interest to all, so a first reading should include parts of this 
Chapter. 


Chapter 16 discusses some tools for debugging and statistics gathering 
based on the concept of embedding function definitions. 


Chapter 17 describes the structure editor, which permits the user to 
construct and modify list structure, including the bodies of interpreted 
functions, and erroneous expressions within the BREAK loop. 


Chapter 18 briefly describes modules of interest that have been 
implemented only recently in PSL, and have not been given Sections or 
Chapters of their own. Currently this includes the PSL cross-reference 
generator, and various macro tools. 


The rest of the manual may be skipped on first reading. 


Chapter 19 describes functions associated with the compiler. Chapter 
20 describes some functions for communicating with the TOPS-20 and UNIX 
operating systems. Chapter 21 describes SYSLISP, a language incorporating 
features from both BCPL and LISP and which is used as an implementation 
language for PSL. Chapter 22 presents details of § the portable 
implementation which may be of interest to sophisticated users, including a 
description of the garbage collector. Chapter 23 describes the extensible 
parser. Section 23.4 provides BNF descriptions of the input accepted by 
the token scanner, standard reader, and syntactic (RLISP) reader. 


Chapter 24 contains the bibliography. 


In Chapter 25 is an alphabetical index of all defined LISP functions and 
globals. Chapter 26 is an alphabetical index of concepts. 
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1.3. The Development of Portable Standard LISP 
[??? put into appendix ???] 


In this Section we give a brief history of the development of PSL and 
mention current and future work. 


In 1966, a model for a standard LISP subset was produced [Hearn 66] as 
part of a general effort to make REDUCE [Hearn 73], a large LISP-based 
algebraic manipulation program, as portable as possible. The goal of this 
work was to define a uniform subset of LISP 1.5 and its variants so that 
programs written in this subset could run on any reasonable LISP system. 


In the intervening years, two deficiencies in the approach taken in the 
original proposal [Hearn 66] emerged. First, in order to be as general as 
possible, the specific semantics and values of several key functions were 
left undefined. Consequently, programs built on this subset could not be 
written with any assumptions made about the form of the values of such 
functions. The second deficiency related to the proposed method of 
implementation of this language. The model considered two versions of LISP 
on any given machine, namely Standard LISP and the LISP of the host 
machine, which we shall refer to as Target LISP. This meant that if any 
definition were stored as interpretive Target LISP, it would vary from 
implementation to implementation; consequently, one could not write 
programs in Standard LISP which needed to assume any knowledge about the 
structure of such forms. This deficiency became apparent during recent 
work on the development of a portable compiler for LISP [Griss 81]. It is 
clearly easier to write a compiler if we deal with a single dialect 
(Standard LISP) than if we must change it to conform with the various 
Target LISPs. 


As a result of this study, we produced a more aggressive definition of 
Standard LISP in the Standard LISP Report [Marti 79]. That paper can serve 
as a standard for a reasonably large subset of LISP with as precise as 
possible a statement about the semantics of each function. 


Recent work has concentrated on producing a complete specification and 
portable implementation of a LISP based on Standard LISP. Experience with 
a Portable LISP Compiler (hereafter PLC) [Griss 81] and with an earlier 
experimental portable LISP implementation [Griss 79a]) has led to the 
current PSL implementation strategy: write most of the system in LISP, 
compiled with the PLC. A small non-LISP kernel is written in a portable, 
LISP-like systems language, SYSLISP. 


The previous systems had the problem that the special implementation 
language (called BIL), although oriented to LISP implementations, was a 
distinet language from LISP, so that communication between "system" code 
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and "LISP" code was difficult. The pattern-driven BIL compiler was not 
very efficient. Consequently, the BIL work resulted in a number of 
experimental LISPs on a number of machines. These implementations were 
quite flexible, portable, and useful for LISP and REDUCE on machines that 
did not already have any LISP, but somewhat inefficient. We therefore 
developed the much more powerful, LISP-like systems language, SYSLISP, in 
which to recode all useful modules. SYSLISP has been targeted to 
high-level languages (such as FORTRAN, PASCAL, C or ADA), and also to 
assembly code. We believe this approach will advance our goal of producing 
a portability strategy which could lead to a system efficient enough for 
realistic experiments with computer algebra and ultimately to portable, 
production quality systems. 


DEC-20 PSL is built by cross-compiling kernel modules written in 
RLISP/SYSLISP to DEC-20 assembly code (currently MIDAS), using a SYSLISP 
compiler running on a previous PSL system. PSL was first bootstrapped from 
a LISP 1.6-based Standard LISP. Additional modules are then loaded as LAP, 
FASL, or are recompiled with the resident compiler. 


VAX PSL was boot-strapped from DEC-20 PSL, and it, too, has a resident 
LAP, FASL, and compiler. 


1.4. Brief Overview of PSL as a Portable Modern LISP 


PSL is an extended Standard LISP, written entirely in itself and SYSLISP 
and compiled with an extended Portable LISP Compiler (with machine-oriented 
extensions). It is to be used as a transportable replacement for the 
various Standard LISP interpreters which we have used to support the REDUCE 
algebra system and other LISP-based tools. The extensions make it more 
efficient and pleasant than Standard LISP for our programming activities 
and allow it to maintain a high degree of compatibility with Standard LISP, 
so that existing software can run without much change. By writing the 
entire LISP in an extended LISP, we are able to more rapidly experiment 
with changes to produce a range of LISP-like systems for other purposes, 
using LISP techniques for debugging even systems code. 


PSL currently provides the following facilities on the DEC-20 and 
VAX-11/750: 


a. A variety of data types, represented as explicitly tagged items: 
id, inum, fixnum, float, bignum, pair, string, code-pointer, 
word-Vector, vector, env-pointer, etc. 


b. Compacting garbage collector on the DEC-20, stop-and-copy on the 
VAX. 
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c. Shallow Binding using a Binding Stack for old values, funarg 
based on Baker's method. 


d. Catch and Throw, used to implement Error/ErrorSet and 
interpreted control structures such as Prog, While, etc. 


e. A single lambda type, corresponding to the interpreted form of 
compiled code. Apply({lambda, code-pointer), [ARGS]) passes the 
ARGS in a set of registers, used by the Standard LISP/SYSLISP 
compiler. Compiled and interpreted code is uniformly called 
through the function cell, which always contains the address of 
executable code. We have chosen the function calling mechanism 
to optimize the speed of calling a compiled function from within 
another compiled function without sacrificing the ability to 
trace or redefine any functions. 


f. All argument processing of the various Spread/Eval/macro 
combinations (expr, fexpr, macro, nexpr), are attributes of an 
id only, not of code or lambdas. This permits uniform, 
efficient compilation. 


g. Resident LISP/SYSLISP Compiler and Loader (LAP), permitting LISP 
and SYSLISP code to be intermixed; FAST loader (FAP). 


h. Stream-directed I/0, with the ability to associate user 
functions (e.g. windows) with any stream; JSYS "native mode" 
1/0 and a clean interface to TOPS-20 via JSYS function enables 
rapid addition of features on the DEC-20; Compress and Explode 
are done as I/O to and from an "in-core file", 


i. Table driven scanner, with user definable scanner-tables (these 
are simply vectors, which can be easily switched); Read-Macros 
and Splice-Macros. 


j. Simple interrupt processing (user hits BREAK computation to 
enter a BREAK Loop, or to return to top-level, or to print name 
of current function), interface for Stack Overflow, Arithmetic 
Overflow, etc. (Not on DEC-20) 


k. TRACE and BREAK packages, invokable within continuable and 
non-fatal errors (a Read-Eval-Print loop before stack unwind); 


has stack backtrace, error correction, LISP-DDT, structure 
editor, primitives to examine some of the Stack and Bstack, 
examine LISP and SYSLISP variables, RETRY a computation that 


caused a continuable-error after correction, etc. 


[??? Relate to features in MACLISP, FranzLISP, CommonLISP, InterLISP, 
etc 272] 


[??? Detail what to avoid in writing code to run on other Standard 
LISPs. Maybe write and talk about a "Lint" program? 277] 


PSL Manual 13 July 1982 Getting Started 
section 2.0 page 2.1 


CHAPTER 2 
GETTING STARTED WITH PSL 


2.1. Purpose of This Chapter 2.1 
2.2. Defining Logical Devices for PSL on the DEC-20 2.1 
2.3. Starting PSL 2.2 
2.3.1. DEC-20 2.2 
2.3.2. VAX-11/750 2.2 
2.4. Running the PSL System 2.3 
2.4.1. Notes on Running PSL and RLISP 2.3 
2.4.2. Transcript of a Short Session with PSL 2.3 
2.5. Error and Warning Messages 2.6 
2.6. Compilation Versus Interpretation 2.7 
2.7. Function Types 2T 
2.8. Flags and Globals 2.8 
2.9. Reporting Errors and Misfeatures 2.8 


2.1. Purpose of This Chapter 


This Chapter is for beginning users of PSL on the DEC-20 and the 
VAX-11/750 at Utah. It also is meant to be a guide to those familiar with 
LISP, and particularly STANDARD LISP, who would like to use PSL as they 
read the manual. . f 


It begins with descriptions of how to set up various logical device 
definitions required by PSL and how to run PSL. A number of miscellaneous 


hints and reminders are given in the remainder of the Chapter. 


2.2. Defining Logical Devices for PSL on the DEC-20 


It is absolutely essential that one say TAKE <PSL>LOGICAL-NAMES.CMD to 
the EXEC before entering PSL. This is not just an option; PSL is written 
to rely on these logical device definitions. For example, "PH:" is defined 
as the directory (or search list) on which PSL looks for help files, "PL:" 
is the directory (or search list) on which PSL looks for Lap and Fasl 
files, etc. One can provide these definitions easily by entering the TAKE 
command given above into one's LOGIN.CMD file. 


There is no equivalent of logical device definitions on the VAX. 


[??? Perhaps we can define standard Csh aliases or variables ??7] 
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2.3. Starting PSL 


2.3.1. DEC-20 

After defining the device names, type either PSL:RLISP or PSL:PSL to the 
at-sign prompt, €. A welcome message indicates the nature of the system 
running, usually with a date and version number. This information may be 
useful in describing problems. [Messages concerning bugs or mis-—features 
should be directed to PSL-BUGS@UTAH-20; see section 2.9.] 


PSL.EXE is a "bare" PSL using LISP (i.e. parenthesis) syntax. This is a 
small core-image and is ideal for simple LISP execution. It also includes 
a resident Fasl, so additional modules can be loaded. In particular, the 
compiler is not normally part of PSL.EXE. 


RLISP.EXE is PSL with additional modules loaded, corresponding to the 
most common system run at Utah. It contains the compiler and an RLISP 
parser. If one types just RLISP to the EXEC, rather than PSL:RLISP, one 
ends up in an older version of RLISP, built upon a LISP 1.6 system. For 


more information about RLISP see Chapter 3. 


It is recommended that file names be of the form "*,s1" or "*,1sp" for 
LISP files, "*.red" for RLISP files, "*.b" for Fasl files, and "*.lap" for 


Lap files. 
2.3.2. VAX-11/750 


The executable files are /usr/local/psl and /usr/local/rlisp. 
Loadable files are /usr/local/lib/ps1/*.b. 
Help files are on /usr/local/lib/psl/help. 


/usr/local/psl is analogous to psl:psl.exe on the DEC-20, and 
/usr/local/rlisp is analogous to psl:rlisp.exe on the DEC-20. This version 
has the RLISP parser and compiler. Additional modules can be loaded from 
/usr/local/lib/psl using the Load function. <Ctr1-C> causes a call to 
Error, and may be used to stop a runaway computation. <Ctrl-Z> or the 
function Quit cause the process to be stopped, and control returned to the 
Shell; the process may be continued. A sequence of <Ctrl1-D>'s (EOF) causes 
the process to be terminated. This is to allow the use of 1/0 redirection 


from the shell. 


Unix only allows 14 characters for file names, and case is significant. 
The use of ".r" instead of ".red" is recommended as the extension for RLISP 
files to save on meaningful characters; other extensions are as on the 
DEC=20. 
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2.4. Running the PSL System 


2.4.1. Notes on Running PSL and RLISP 


a. Use Help(); [(Help) in LISP] for general help or an indication 
of what help is available; use Help (a, b, c); [(Help a bc) in 
LISP] for information on topics a, b, and c. This call prints 
files from the PH: (i.e. <PSL.HELP>) directory. Try Help x; 
[(Help x) in LISP] on: 


? Exec Mini Step 

Br Find MiniEditor Strings 
Break Flags MiniTrace TopLoop 
Bug For Package Tr 
Debug Globals PRLISP Trace 
Defstruct GSort PSL UnBr 
Edit Help RCREF UnTr 
EditF JSYS RLISP Useful 
Editor Load ShowFlags ZFiles 
Emode Manual Slate ZPEdit 
EWindow 


[??? Help() does not work in RLISP ???] 


b. File I/O needs string-quotes (") around file names. File names 
may use full TOPS-20 or UNIX conventions, including directories, 
sub-directories, etc. 


Input in RLISP mode is done using the In "File-Name"; command. 
Use (Dskin "File-Name") for input from LISP mode. 
‘For information on similar. 1/0 functions see Chapter 13. 


c. Use Quit; [(Quit) in LISP] or <Ctrl1-C> on the DEC-20 (<Ctrl-Z> 
on the VAX) to exit. <Ctrl-C> (<Ctrl-Z> on the VAX) is useful 
for stopping run-away computations. On the DEC-20, typing START 
or CONTINUE to the @ prompt from the EXEC usually restarts in a 
reasonable way. 


2.4.2. Transcript of a Short Session with PSL 
The following is a transcript running RLISP on the DEC-20. 


@psl:rlisp 
[RLISPO] 
PSL 3.0 Rlisp, 28-Jun-82 
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[1] % Notice the numbered prompt. 
[1] % Comments begin with "%" and do not change the prompt number. 


[1] Z t= !(1 2 3); % Make an assignment for Z. 

(1 2 3) 

[2] Cdr Z; % Notice the change in the prompt number. 
(2 3) 

[3] Lisp Procedure Count L; % "Count" counts the number of elements 
[3] If Null L Then 0 4 in a list L. 

[3] Else 1 + Count Cdr L; 

COUNT 

[4] Count Z; % Try out "Count" on Z. 

3 

[5] % To find out how to use the trace 

[5] Help MiniTrace; % funetion use the function "Help". 


The Mini-Trace Package: 


The following 4 functions (all FEXPRs) are defined: 
(they each redefine the functions, saving an old definition) 


TR ([F:id]) Cause TRACE message to be printed on entry to 
and exit from calls to the functions F1 ... Fn. 

UNTR ([F:id]) Restore original definitions 

BR ([F:id]) Cause BREAK on entry and on exit from functions, 


permitting arguments and results to be examined 
and modified. 


UNBR ([F:id]) Restore original definitions of the functions 
F1. eee Fn. a 

Fluids: 

TrSpace!* Controls indentation, may need to be reset to 0 
in "funny" cases, 

!*NoTrArgs Set to T to suppress printing of arguments of 


traced functions. 


[See also the Full DEBUG package (do Help Debug; in RLISP, (Help 
Debug) in LISP).] 


NIL 

[6] % Trace the recursive execution of "Count". 
[6] Tr Count; % Notice that this causes redefintion. 

*** Function "COUNT" has been redefined 

NIL 


[7] % A call on "Count" now shows the value of 
[7] % "Count" and of its argument each time it 
[7] Count Z; % is called. 
COUNT 1: Argt:=(1 2 3), 
COUNT 2: Arg1:=(2 3), 
COUNT 3: Argi:=(3), 

COUNT 4: Arg1:=NIL, 

COUNT 4:=0 
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COUNT 3:=1 
COUNT 2:=2 
COUNT 1:=3 


[8] Lisp Procedure Factorial X; 
[8] If X <= 1 Then 1 
[8] Else X * Factorial (X-1); 
FACTORIAL 
[9] Tr Factorial; 
*** Function "FACTORIAL" has been redefined 
NIL 
[10] Factorial 4; % Trace execution of "Factorial", 
FACTORIAL 1: Arg1:=4, 
FACTORIAL 2: Arg1:=3, 
FACTORIAL 3: Arg1:=2, 
FACTORIAL 4: Arg1:=1, % Notice values being returned. 
FACTORIAL 4:=1 
FACTORIAL 3:=2 
FACTORIAL 2:=6 
FACTORIAL 1:=24 


24 

? Print this message, listing active Break IDs 

T Print stack backtrace 

Q Exit break loop back to ErrorSet 

C Return last value to the ContinuableError call 

R Reevaluate ErrorForm!* and return o 

M Display ErrorForm!* as the "message" 

E Invoke a simple structure editor on ErrorForm!* 
(For more information do Help Editor.) 

I Show a trace of any interpreted functions 


See the manual for details on the Backtrace, and how ErrorForm!* is 
set. The Break Loop attempts to use the same TopLoopRead!* etc, as 
the calling top loop, just expanding the PromptString!*. 

NIL 

2 lisp break> % Get a Trace-Back of the 

2 lisp break> I % interpreted functions. 

MAIN COUNT COND PLUS PLUS2 COUNT CDR TOPLOOP APPLY BREAKEVAL 

NIL 

3 lisp break> Q % To exit the Break Loop. 

[13] % Load in a file, showing the file 

[13] In "small-file.red";  % and its execution. 

X := 'A . 'B NILSCA B) % Construct a list with "." for Cons. 


Count X;2 % Call "Count" on X. 

Reverse X;(B A) % Call "Reverse" on X. 

NIL 

[14] % This leaves RLISP and enters 
[14] End; % LISP mode. 


Entering LISP... 


page 2.5 
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PSL 3.0, 9-Jun-82 
6 lisp> (SETQ X 3) 
3 


7 lisp> (FACTORIAL 3) 
6 

8 lisp> (BEGINRLISP) 
Entering RLISP... 
[15] Quit; 

@continue 
"Continued" 

[16] X; 

3 

[17] ^C 

@start 

[18] Quit; 

@ 


13 July 1982 


% A LISP assignment statement. 


4% Call "Factorial" on 3. 


| 


section Ky 


% This function returns us to RLISP. 


% To exit call "Quit". 


% Notice the prompt number. 


% One can also quit with <Ctrl-C>. 


% Alternative immediate re-entry. 


2.5. Error and Warning Messages 


Many functions 


details); in many cases, an error message is printed. 
are given as part of a function's definition in 
preceded by five stars (*); a warning message is preceded by 
type 
an error message if an argument is incorrect. 


message is 
three. 
arguments 


For example, most primitive 
and display 
type mismatch error mentions the function in which the error was 


the manual. 


functions check the 


give the expected type, and print the actual value passed. 


Sometimes one sees a prompt of the form: 


Do you really want to redefine 


This means 


required. 


N, Yes, or No to the query. 
affirmative response is extremely 


are a system expert. 
different name. 


you have -tried to 
function used by the PSL system. 
B starts a break loop. 


the system function ~FOO'? 


A Y, N, YES, NO, or B 


See 


A common warning message is 


*** Function "FOO" has been redefined 


If this occurs without the 


function. 
in again. 


query above, you are 


redefining your 
This happens normally if you read a file, edit it, and read it 


detect and signal appropriate errors (see Chapter 15 for 
The error conditions 


An error 


of their 
The 
detected, 


define a function with the same name as a 


response is 


After quitting the break loop, answer Y, 
the definition of YesP in Chapter 14. An 
dangerous and should be given only if you 
Usually this means that your function must be given a 


own 


Y 
| 


| 
Getting Started 
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The flag !*Usermode, described in section 12.2, can be set to suppress 
these warning messages. 


2.6. Compilation Versus Interpretation 


PSL uses both compiled and interpreted code. If compiled, a function 
usually executes faster and is smaller. However, there are some semantic 
differences of which the user should be aware. For example, some recursive 
functions are made non-recursive, and certain functions are open-compiled. 
A call to an open-compiled function is replaced, on compilation, by a 
series of online instructions instead of just being a reference to another 
function. Functions compiled open may not do as much type checking. The 
user may have to supply some declarations to control this behavior. 


The exact semantic differences between compiled and interpreted functions 
are more fully discussed in Chapter 19 and in the Portable LISP Compiler 
paper [Griss 81]. 


[??? We intend to consider the modification of the LISP semantics so as 
to ensure that these differences are minimized. If a conflict occurs, 
we will restrict the interpreter, rather than extending (and slowing 
down) the capabilities of the compiled code. ???] 


- We indicate on the function definition line if it is typically compiled 
OPEN; this information helps in debugging code that uses “these functions. 
These functions do not appear in backtraces and cannot be redefined, traced 
or broken in compiled code. 


[??2? Should we make open-compiled functions totally un-redefinable 
without special action, even for interpreted code. Consistency! E.g. 
flag 'COND LOSE. ???] 


2.7. Function Types 


Eval-type functions are those called with evaluated arguments. NoEval 


functions are called with unevaluated arguments. Spread-type functions 
have their arguments passed in a one-to-one correspondence with their 


formal parameters. NoSpread functions receive their arguments as a single 
list. 


There are four function types implemented in PSL: 


expr An Eval, Spread function, with a maximum of 15 arguments. In 
referring to the formal parameters we mean their values. 
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fexpr A NoEval, NoSpread function. There is no limit on the number of 
arguments. In referring to the formal parameters we mean the 
unevaluated argument. 


nexpr An Eval, NoSpread function. 
macro The macro is a function which creates a new S-expression for 


subsequent evaluation or compilation. There is no limit to the 
number of arguments a macro may have. The descriptions of the 
Eval and Expand functions in Chapter 11 provide precise details. 


2.8. Flags and Globals 


Generally, flag names begin with !* and global names end with !*,where 
ie Si is an escape character. One can set a flag !*xxx to T by using On 
xxx; in RLISP [(on xxx) in LISP]; one can set it to NIL by using Off xxx; 
in RLISP [(off xxx) in LISP]. For example) !*ECHO, !*PVAL and !*PECHO are 
flags that control Input Echo, Value Echo and Parse Echo. These flags are 
described more fully in Chapters 13 and 14. ; 


For more information, type "HELP FLAGS;" or "HELP GLOBALS;", or see 
Chapter 12. l 


2.9. Reporting Errors and Misfeatures 


Send MAIL to PSL-BUGS@UTAH-20. This remails messages to a number of 
users on a mailing list, and place a message in <PSL>USER-BUGS.TXT. 


Bug (): undefined DEC-20 only, expr 
The function Bug(); can be called from within PSL:RLISP. This 
starts MAIL (actually MM) in a lower fork, with the To: line set 


up to Griss and Benson. Simply type the subject of the 
complaint, and then the message. 


After typing message about a bug or a misfeature end finally with 
a <Ctrl-Z>. 


<Ctrl-N> aborts the message. 


[?2?? needs flags ???] 


J 


J 


E 


J 


J 


J 


C 


J 
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CHAPTER 3 
RLISP SYNTAX 


3.1. Motivation for RLISP Interface to PSL 
3.2. An Introduction to RLISP 
3 


. 


3.2.1. LISP equivalents of some RLISP constructs 
.3. An Overview of RLISP and LISP Syntax Correspondence 
1. Function Call Syntax in RLISP and LISP 
2. RLISP Infix Operators and Associated LISP Functions 
3. Differences between Parse and Read 
4. Procedure Definition 
-5. Compound Statement Grouping 
6 
T 
i 


e 


. Blocks with Local Variables 
. The If Then Else Statement 


3.4. 


1. While Loop 

2. Repeat Loop 
.3. For Each Loop 
y 
5 


. For Loop 


-5. Loop Examples 
g Syntax 
.1. RLISP I/O Syntax 


e Ww) Wo 0 OO) OO OD WW WW Us UU OW Uy Uy) 
o 


He 
-à 0 


3.5. 


W MO UY U) WU ESU eee 

po] 

53 

0a 

UN 

cr 

w 

cr 

om 

3 

O 

3 

ct 

a 

Ld 
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3.1. Motivation for RLISP Interface to PSL 


Most of the PSL users at Utah prefer to write LISP code using a 
ALGOL-like (or PASCAL-like) preprocessor language, RLISP, because of its 
Similarity to the heavily used PASCAL and C languages. RLISP was developed 
as part of the REDUCE Computer Algebra project [Hearn 73], and is the 
ALGOL-like user language as well as the implementation language. RLISP 
provides a number of syntactic niceties which we find convenient, such as 
vector subscripts, case statement, If-Then-Else, etc. We usually do not 
distinguish LISP from RLISP, and can mechanically translate from one to the 
other in either direction using a parser and pretty-printer written in PSL. 
That is, RLISP is a convenience, but it is not necessary to use RLISP 
syntax rather than LISP. Some PSL functions in this manual are accompanied 
by a definition in RLISP; such definitions are guides to the function's 
semanties rather than exact copies of code used. Sometimes a LISP 
S-expression form is also given, if it is not simply related to the RLISP 
form. The exact definitions of all PSL functions can be found in the 
sources (see Chapter 22 for a guide to the PSL sources). A complete 
BNF-like definition of RLISP and its translation to LISP using the MINI 
system is given in Section 23.4. Also discussed in Chapter 23 is an 
extensible table driven parser which is used for the current RLISP parser. 
There we give explicit tables which define RLISP syntax. 
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In this Chapter we provide enough introduction to make the examples and 
sources readable, and to assist the user to write RLISP code. 


3.2. An Introduction to RLISP 


An RLISP program consists of a set of functional commands which are 
evaluated sequentially. RLISP expressions are built up from declarations, 
statements and expressions. Such entities are composed of sequences of 
numbers, variables, operators, strings, reserved words and delimiters (such 
aS commas and parentheses), which in turn are sequences of characters. The 
evaluation proceeds by a parser first converting the ALGOL-like RLISP 
source language into LISP S-expressions, and evaluating and printing the 
result. The basic cycle is thus Parse-Eval-Print, although the specific 
functions, and additional processing, are under the control of a variety of 
flags, described in appropriate Sections. 


3.2.1. LISP equivalents of some RLISP constructs 

The following gives a small set of RLISP statements and functions and 
their corresponding LISP forms. To see the exact LISP equivalent of RLISP 
code, set the flag !*PECHO to T [On PEcho; in RLISP]. 


Assignment statements in RLISP and LISP: 
A (SETQ X 1) 


A procedure to take a factorial 
in RLISP: 
LISP PROCEDURE FACTORIAL N; 
IF N <= 1 THEN 1 
ELSE N * FACTORIAL (N-1); 


in LISP: 
(DE FACTORIAL (N) 
(COND ((LEQ N 1) 1) 
€ T (TIMES N (FACTORIAL (DIFFERENCE N 1)))))) 


. Take the Factorial of 5 in RLISP and in LISP: 
FACTORIAL 5; (FACTORIAL 5) 


Build a list X as a series of "Cons"es 
in RLISP: 
X := 'A . TB. 'C . NIL; 


in LISP: 
(SETQ X (CONS 'A 
(CONS 'B 
(CONS 'C NIL)))) 
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3.3. An Overview of RLISP and LISP Syntax Correspondence 


The RLISP parser converts RLISP expressions, typed in at the terminal or 
read from a file, into directly executable LISP expressions. For 
convenience in the following examples, the "==>" arrow is used to indicate 
the LISP actually produced from the input RLISP. To see the LISP 
equivalents of RLISP code on the machine, set the flag !*PECHO to T [On 


Pecho; in RLISP]. As far as possible, upper and lower cases are used as 
follows: 


a. Upper case tokens and punctuation represent items which must 
appear as is in the source RLISP or output LISP. 


b. Lower case tokens represent other legal RLISP constructs or 
corresponding LISP translations. We typically use "e" for 
expression, "s" for statement, and "v" for variable; "list" is 
tacked on for lists of these objects. 


For example, the following rule describes the syntax of assignment in 
RLISP: 


= number; 
==> (SETQ VAR number) 


Another example: 


IF expression THEN action _1 ELSE action 2 
==> (COND ((expression action 1) (T action 2))) 


In RLISP, a function is recognized as an "ftype" (one of the tokens EXPR, 
FEXPR, etc. or none) followed by the keyword PROCEDURE, followed by an "id" 
(the name of the function), followed by a "v-list" (the formal parameter 
names) enclosed in parentheses. A semicolon terminates the title line. 
The body of the function is a <statement> followed by a semicolon. In LISP 
syntax, a function is defined using one of the "Dx" functions, i.e. one of 
De, Df, Dm, or Dn, depending on "ftype". For example: 


EXPR PROCEDURE NULL(X); 
EQ(X, NIL); 
==> (DE NULL (X) (EQ X NIL)) 
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3.3.1. Function Call Syntax in RLISP and LISP 

A function call with N arguments (called an N-ary function) is most 
commonly represented as "FN(X1, X2, ... Xn)" in RLISP and as 
"(FN X1 X2 ... Xn)" in LISP. Commas are required to separate the arguments 
in RLISP but not in LISP. A zero argument function call is "FN()" in RLISP 
and "(FN)" in LISP. An unary function call is "FN(a)" or "FN a" in RLISP 
and "(FN a)" in LISP; i.e. the parentheses may be omitted around the single 
argument of any unary function in RLISP. 


3.3.2. RLISP Infix Operators and Associated LISP Functions 

Many important PSL binary functions, particularly those for arithmetic 
operations, have associated infix operators, consisting of one or two 
Special characters. The conversion of an RLISP expression "A op B" to its 
corresponding LISP form is easy: "(fn AB)", in which "fn" is the 
associated function. The function name fn may also be used as an ordinary 
RLISP function call, "fn(A, B)". 


Refer to Chapter 23 for details on how the association of "op" and "fn" 
is installed. 


Parentheses may be used to specify the order of combination. 
"((A op_a B) op_b C)" in RLISP becomes "(fn_b (fn_a A B) C)" in LISP. 


If two or more different operators appear in a sequence, such as 
"A op a B op b C", grouping (similar to the insertion of parentheses) is 
done based on relative precedence of the operators, with the highest 
precedence operator getting the first argument pair: "(A op a B) op b C" 
if Precedence(op a) >= Precedence(op b); "A op a (B op b C)" if 
Precedence(op a) < Precedence(op b). 


If two or more of the same operator appear in a sequence, such as 
"A op B op C", grouping is normally to the left (Left Associative; i.e. 
"(fn (fn A B) C)"), unless the operator is explicitly Right Associative 
(such as . for Cons and := for SetQ; i.e. "(fn A (fn B C))"). 


The operators + and * are N-ary; i.e. "A nop B nop C nop B" parses into 
"(nfn A B C D)" rather than into "(nfn (nfn (nfn A B) C) D)". 


The current binary operator-function correspondence is as follows: 
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Operator Function Precedence 

Ñ Cons 23 Right Associative 
ex Expt f 23 

/ Quotient 19 

* Times 19 N-ary 

- Difference 17 

+ Plus 17 Neary 

Eq Eq 15 

= Equal 15 

>= Geq 15 

> GreaterP 15 

<= Leq 15 

< LessP 15 

Member Member 15 

Memq MemQ 15 

Neq Neq 15 

And And 11 Neary 

Or Or 9 Neary 

t= SetQ 7 Right Associative 


Note: There are other INFIX operators, mostly used as key-words within 
other syntactic constructs (such as Then or Else in the If-..., or Do in 
the While-..., etc.). They have lower precedences than those given above. 
These key-words include: the parentheses "()", the brackets "[]", the colon 
"et. the comma ",", the semi-colon ";", the dollar sign "$", and the ids: 
Collect, Conc, Do, Else, End, Of, Procedure, Product, Step, Such, Sum, 
Then, To, and Until. 


As pointed out above, an unary function FN can be used with or without 
parentheses: FN(a); or FN a;. In the latter case, FN is assumed to behave 
as a prefix operator with highest precedence (99) so ‘that "FOO 1 ** 2" 
parses as "FOO(1) ** 23", The operators +, -, and / can also be used as 
unary prefix operators, mapping to Plus, Minus and Recip, respectively, 
with precedence 26. Certain other unary operators (RLISP key-words) have 
low precedences or explicit special purpose parsing functions. These 
include: BEGIN, CASE, CONT, EXIT, FOR, FOREACH, GO, GOTO, IF, IN, LAMBDA, 
NOOP, NOT, OFF, ON, OUT, PAUSE, QUIT, RECLAIM, REPEAT, RETRY, RETURN, 
SCALAR, SHOWTIME, SHUT, WHILE and WRITE. 
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3.3.3. Differences between Parse and Read 
= A single character can be interpreted in different ways depending on 
context and on whether it is used in a LISP or in an RLISP expression. 
Such differences are not immediately apparent to a novice user of RLISP, 
but an example is given below. 


The RLISP infix operator ".' may appear in an RLISP expression and is 
converted by the Parse function to the LISP function Cons, as in the 
expression x := 'y . 'z3. A dot may also occur in a quoted expression in 
RLISP mode, in which case it is interpreted by Read as part of the notation 
for pairs, as in (SETQ X '(Y .Z)). Note that Read called from LISP or 
from RLISP uses slightly different scan tables (see Chapter 13). In order 
to use the function Cons in LISP one must use the word Cons in a prefix 


position. 


3.3.4. Procedure Definition 

Procedure definitions in PSL (both RLISP and LISP) are not nested as in 
ALGOL; all appear at the same top level as in C. The basic function for 
defining procedures is PutD (see Chapter 10). Special syntactic forms are 


provided in both RLISP and LISP: 


noes a PROCEDURE name(v 1,...,v_n); body; 
=> (Dx name (v_1 ... v_N) body) 


Examples: 


PROCEDURE ADD1 N; 
N+1; 
=> (DE ADD1 (N) (PLUS N 1)) 


MACRO PROCEDURE FOO X; 


renee CDR X, CDR X); 
=> (DM FOO (X) (LIST 'FUM (CDR X) (CDR X)) 


The value returned by the procedure is the value of the body: no 
assignment to the function name (as in ALGOL or PASCAL) is needed. 


In the general definition given above "mode" is usually optional; it can 
be LISP or SYMBOLIC (which mean the same thing) or SYSLISP [only of 
importance if SYSLISP and LISP are inter-mixed]. "Ftype" is expr, fexpr, 
macro, nexpr, or  smacro (or can be omitted, in which case it defaults to 
expr). Name(v_ do vo N) is any legal form of call, including infix. Dx 
is De for expr, Df for fexpr, Dm for macro, Dn for nexpr, and Ds for 
smacro. 


The smacro is a simple substitution macro. 
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SMACRO PROCEDURE ELEMENT X; % Defines ELEMENT(x) to substitute 


CAR CDR (X): % as Car Cdr x; 
==> (DS ELEMENT (X) (CAR (CDR X))) 


In code which calls ELEMENT after it was defined, ELEMENT(foo); behaves 
exactly like CAR CDR foo;. 


3.3.5. Compound Statement Grouping 

A group of RLISP expressions may be used in any position in which a 
Single expression is expected by enclosing the group of expressions in 
double angle brackets, << and >>, and separating them by the ; delimiter. 


The RLISP <<A; B; C; ... Z>> becomes (PROGN ABC... Z) in LISP. The 
value of the group is the value of the last expression, Z. 
Example: 


X2=<<PRINT X; X+1>>3 % prints old X then increments X 
==> (SETQ X (PROGN (PRINT X) (PLUS X 1))) 


3.3.6. Blocks with Local Variables 

A more powerful construct, sometimes used for the same purpose as the 
<< >> Group, is the Begin-End block in RLISP or Prog in LISP. This 
construct also permits the allocation of 0 or more local variables, 
initialized to NIL. The normal value of a block is NIL, but it may be 
exited at a number of points, using the Return statement, and each can 


return a different value. Tne block also permits labels and a GoTo 
construct. 


Example: 


BEGIN SCALAR X,Y; % SCALAR declares locals X and Y 
X:='(1 2 3); 
L1: IF NULL X THEN RETURN Y; 
Y:=CAR X; 
X:=CDR X; 
GOTO L1; 
END; 


==> (PROG (X Y) 
(SETQ X '(1 2 3) 
L1 (COND ((NULL X) (RETURN Y))) 
(SETQ Y (CAR X)) 
(SETQ X (CDR X)) 
(GO L1)) 
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3.3.7. The If Then Else Statement 
RLISP provides an If statement, which maps into the LISP Cond statement. 
See Chapter 9 for full details. For example: 


IF e THEN s; 
==> (COND (e s)) 


IF e THEN s1 ELSE s2; 
==> (COND (e s1) (T s2)) 


IF e1 THEN s1 
ELSE IF e2 THEN s2 


ELSE s3; 
==> (COND (e1 s1) 
(e2 s2) 
(T s3)) 


3.4. Looping Statements 


RLISP provides While, Repeat, For and For Each loops. These are 
discussed in greater detail in Chapter 9. Some examples follow: 


3.4.1. While Loop 


WHILE e DO s; % As long as e NEQ NIL, do s 
== (WHILE e s) 


3.4.2. Repeat Loop 


REPEAT s UNTIL e; % repeat doing s until "e" is not NIL 
== (REPEAT s e) 


3.4.3. For Each Loop 
The For Each loops provide various mapping options, processing elements 
of a list in some way and sometimes constructing a new list. 


FOR EACH x IN y DO s; % y is a list, x traverses list 
% Bound to each element in turn 


==> (FOREACH x IN y DO s) 


FOR EACH x ON y DO s; % y is a list, x traverses list 


% Bound to successive Cdr's of y 
==> (FOREACH x ON y DO s) 


J 


& 


J 


J 


J 


C 


J 


d 


L 
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% Other options can return modified lists, etc. See Chapter 9. 


3.4.4, For Loop 
The For loop permits an iterative form with a compacted control variable. 


FOR i := a:b DO s; % step i successively from a to b in 
% steps of 1 
==> (FOR (FROM I a b 1) DO s) 


FOR i := a STEP b UNTIL c DO s; % More general stepping 
==> (FOR (FROM I a c b) DO s) 


% Other options can compute sums and products. 
3.4.5. Loop Examples 


LISP PROCEDURE count lst; % Count elements in lst 
BEGIN SCALAR k; 
k==07 
WHILE PAIRP lst DO <<k:=k+1; 1lst:=CDR 1st>>; 
RETURN k; 
END; 


==> (DE COUNT (LST) 
(PROG (K) 
(SETQ K 0) 
(WHILE (PAIRP LST) 
(PROGN 

(SETQ K (PLUS K 1)) 
(SETQ LST (CDR LST)))) 

(RETURN K))) 


or 


LISP. PROCEDURE CountNil 1st; % Count NIL elements in lst 
BEGIN SCALAR k; 

k:=0; 

FOR EACH x IN lst DO If Null x then k:=k+1; 

RETURN k; 
END; 


==> (DE COUNTNIL’ (LST) 
(PROG (K) 
(SETQ K 0) 
(FOREACH X IN LST DO (COND 
( (NULL X) (SETQ K (PLUS K 1))))) 
(RETURN K))) 
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3.5. Flag Syntax 


Two declarations are offered to the user for turning on or off a variety 
of flags in the system. Flags are global variables that have only the 
values Tor NIL. By convention, the flag name is XXXX, but the associated 
global variable is !*XXXX. The RLISP commands ON and OFF take a list of 
flag names as argument and turn them on and off respectively (i.e. set the 
corresponding !* variable to T or NIL). 


Example: 


ON ECHO, FEE, FUM; % Sets !*ECHO, !*FEE, !*FUM to T; 
==> (ON '(ECHO FEE FUM)) 


OFF INT,SYSLISP; % Sets !*INT and !*SYSLISP to NIL 
==> (OFF '(INT SYSLISP)) 


[??? Mention SIMPFG property ???] 
See Chapter 12 for a complete set of flags and global variables. 


3.5.1. RLISP I/O Syntax 

RLISP provides special commands to OPEN and SELECT files for input or for 
output and to CLOSE files. File names must be enclosed in "....". Files 
with the extension ".sl" or ".lsp" are read by In in LISP mode rather than 
RLISP mode. i 


IN "<griss.stuff>fff.red","ggg.lsp"; % First reads fff.red 
% Then reads ggg.lsp 


OUT "keep-it.output"; % Diverts output to "keep-it.output" 
OUT "fum"; % now to fum, keeping the other open 
SHUT "fum"; % to close fum and flush the buffer 


File names can use the full system conventions. See Chapter 13 for more 
detail on 1/0. l 
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4.3. Converting Data Types 


4.1. Data Types Supported in PSL 


Data objects in PSL are tagged with their type. This means that the type 
declarations required in many programming languages are not needed. Some 
functions are "Generic" in that the result they return depends on the types 
of the arguments. A tagged PSL object is called an item, and has a tag 
field (9 bits on DEC-20), an info field (18 bits on DEC-20), and some bits 
for garbage collection. The info field is either immediate data or an 
index or address into some other structure (such as the heap or id space). 
For the purposes of input and output of items, an appropriate notation is 
used (see Chapter 13 for full details on syntax, restrictions, etc.). More 
explicit implementation details can be found in Chapters 21 and 22. 


The basic data types supported in PSL and a brief indication of their 
representation are described below. 


integer The integers are also called "fixed" numbers. The magnitude 
of integers is essentially unrestricted if BIG is loaded. 
The notation is a sequence of digits in an appropriate radix 
(radix 10 is the default, which can be overridden by a radix 
prefix, such as 2#, 8#, 16# etc). There are three internal 


representations of integers, chosen to suit the 
implementation: 
inum A signed number fitting into info. Inums do not 


require dynamic storage and are represented in the 
same form as machine integers. (19 bit [-2%18 ... 
2°18 - 1] on the DEC-20, 28 bit on the VAX.) 

fixnum A full-word signed integer, allocated in the heap. 
(36 bit on the DEC-20, fitting into a register; 32 
bit on the VAX.) 
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float 


air 


vector 


string 
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[??? Do we need fixnums, and if yes how large 
227] 


bignum A signed integer of arbitrary precision, allocated 
as a vector of integers. Bignums are currently not 
installed by default; to use them, do LOAD BIG;. 


A floating point number, allocated in the heap. The 
precision of floats is determined solely by the 
implementation, and is 72-bit double precision on the DEC-20, 
64-bit on the VAX. The notation is a sequence of digits with 
the addition of a single floating point ( . ) and optional 
exponent (E <integer>). (No spaces may occur between the 
point and the digits). Radix 10 is used for representing the 
mantissa and the exponent of dty(floating point) numbers. 


An identifier (or id) is an item whose info field points to a 
five-item structure containing the print name, property cell, 
value cell, function cell, and package cell. The id space 
contains the pointers and structures. The notation for an id 
is an alphanumeric character sequence, starting with a 
letter. If presented with an appropriate identifier 
character string, the PSL reader usually finds a unique id to 
associate with this string. See Chapters 6 and 13 for more 
information on the fields, specific id syntax, escape 
characters, case conversion, etc. 


A primitive two-item structure which has a left and right 
part. A notation called dot-notation is used, with the form: 
(<Left-Part> . <Right-Part>). The <left-part> is known as 
the Car portion and the <right-part> as the Cdr portion. The 
parts may be any item. (Spaces are used to resolve ambiguity 
with floats; see Chapter 13). 


A primitive uniform structure of items; an integer index is 
used to access random values in the structure. The 
individual elements of a vector may be any item. Access to 
vectors is by means of functions for indexing, sub-vector 
extraction and concatenation, defined in Section 8.3. In the 
notation for vectors, the elements of a vector are surrounded 
by square brackets: [item-0 item-1 ... item-n]. 


A packed vector (or byte vector) of characters; the elenents 
are small integers representing the ASCII codes for the 
characters (usually inums). The elements may be accessed by 
indexing, sub-string and concatenation functions, defined in 
Chapter 8. String notation consists of a series of 
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characters enclosed in double quotes, as in "THIS IS A 
STRING". A quote is included by doubling it, as in "HE SAID, 
nn ISp"!", (Input strings may cross the end-of-line 
boundary, but a warning is given.) See !*EOLINSTRINGOK in 
Chapter 13. 


w-vector A vector of machine-sized words, used to implement such 
things as fixnums, bignums, etc. The elements are not 
considered to be items, and are not examined by the garbage 
collector. 

(27? The wevector could be used to implement machine-code 
blocks on some machines. ??7] 

Byte-Vector vector of bytes. Internally a byte-vector is the same as a 
string, but it is printed differently as a vector of integers 
instead of characters. 

Halfword-Vector 


$ 


vector of machine-sized halfwords. 


code-pointer This item is used to refer to the entry point of compiled 


env-pointer 


Others 


functions (exprs, fexprs, macros, etc.), permitting compiled 
functions to be renamed, passed around anonymously, etc. New 
code-pointers are created by the loader (Lap,Fasl) and 
associated functions. . 


A data type used to support a funarg capability. [not 
implemented yet] 


An implementation may have functions which deal with specific 
data types other than those listed above. The use of these 
entities is to be avoided in portable PSL code (see Chapters 
21 and 22 for more details.) These include low-level, 
machine-dependent SYSLISP objects, such as: 


s-integer An untagged word, or multi-word on some machines, 
used to represent a machine-level integer. This is 
used to communicate with the SYSLISP level and with 
some operating system services. Inums are a subset 
of s-integers. s-integers will be phased out 
eventually. 

word — A true machine word, the size of which is 
implementation-dependent (36 bits on DEC-20, same 
size as item, fits in one register, etc.). 
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[?2?? Other low-level types ???] 


4.1.1. Other Notational Conventions 

Certain functional arguments can be any of a number of types. For 
convenience, we give these commonly used sets a name. We refer to these 
sets as "classes" of primitive data types. In addition to the types 
described above and the names for classes of types given below, we use the 
following conventions in the manual. {XXX, YYY} indicates that either data 
type XXX or data type YYY will do. {XXX}-{YYY} indicates that any object 
of type XXX can be used except those of type YYY; in this case, YYY is a 
subset of XXX. For example, {integer, float} indicates that either an 
integer or a float is acceptable; {any}-{vector} means any type except a 
vector. 


any Any of the types given above. An S-expression is another 
term for any. All PSL entities have some value unless an 
error occurs during evaluation. 


atom The class {any}~{pair}. 

boolean The class of global variables {T, NIL}, or their respective 
values, {T, NIL}. (See Chapter 12). 

character Integers in the range of 0 to 127 representing ASCII 
character codes. These are distinct from single-character 
ids. 

constant The class of (integer, float, string, vector, code-pointer). 


A constant evaluates to itself (see the definition of Eval 
in Chapter 11). 

extra-boolean Any value in the system. Anything that is not NIL has the 
boolean interpretation T. 

ftype The class of definable function types. The set of ids 
{expr, fexpr, macro, nexpr [not implemented yet]}. 
The ftype is ONLY an attribute of identifiers, and is not 
associated with either executable code (code-pointers) or 
lambda expressions. 


io-channel A small integer representing an io channel. 

number The class of {integer, float}. 

x-vector Any Kind of vector; i.e. a string, vector, w-vector, or 
word. 

Undefined An implementation-dependent value returned by some low-level 


functions; i.e. the user should not depend on this value. 
None Returned A notational convenience used to indicate control functions 
that do not return directly to the calling point, and hence 
do not return a value. (e.g. Go) 


4.1.2. Structures 

Structures are entities created using pairs. Lists are structures very 
commonly required as parameters to functions. If a list of homogeneous 
entities is required by a function, this class is denoted by xxx-list, in 
which xxx is the name of a class of primitives or structures. Thus a list 
of ids is an id-list, a list of integers is an integer-list, and so on. 
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list A list is recursively defined as NIL or the pair (any + list). A 


a-list 


form 


lambda 


function 


special notation called list-notation is used to represent lists. 
List-notation eliminates extra parentheses and dots. The list 
(a . (bD . (c +» NIL))) in list-notation is (a bc). List-notation 
and dot-notation may be mixed, as in (a b . c) or (a (b . c) d), 
which are equivalent to (a . (b . c)) and 
(a . ((b. c) . (d . NIL))), respectively. (See Section 3.3.3.) 
Note: () is an alternate input representation of NIL. 


Án association list; each element of the list is a pair, the Car 
part being a key associated with the value in the Cdr part. 


Any list which is legally acceptable to Eval; that is, it is 
syntactically and semantically accepted by the interpreter or the 
compiler. (See Chapter 11 for more details.) 


A lambda expression which must have the form (in list-notation): 
(LAMBDA parameters . body). "Parameters" is an id-list of 
formal parameters for "body", which is a form to be evaluated 
(note the implicit ProgN). The semantics of the evaluation are 
defined with the Eval function (see Chapter 11). 


A lambda, or a code-pointer to a function. A function is always 
evaluated as an Eval, Spread form. 


4.2. Predicates Useful with Data Types 


Most functions in this Section return T if the condition defined is met 


and NIL 


if it is not. Exceptions are noted. Defined are type-checking 


functions and elementary comparisons. 


4.2.1. Functions for Testing Equality 


[??? This stuff should probably be expanded for the folks who aren't 
too terribly familiar with LISP 777] 


Functions for testing equality are listed below. For other functions 
comparing arithmetic values see Chapter 5. 


Eq (Usany, Vsany): boolean open-compiled, expr 


Returns T if U points to the same object as V, i.e. if they are 
identical items. Eq is not a reliable comparison between numeric 
arguments. This function should only be used in special 
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circumstances. Normally, equality should be tested with Equal, 
described below. 
EQN (Usany, V:any): boolean expr 


Returns T if U and V are Eq or if U and V are numbers and have 
the same value and type. 


[??? Should numbers of different type be EqN? e.g. O vs. 0.0 


222] 
Equal (U:any, V:any): boolean 4 expr 
Returns T if U and V are the same. Pairs are compared 
recursively to the bottom levels of their trees. Vectors must 


have identical dimensions and Equal values in all positions. 
Strings must have identical characters, i.e. all characters must 
be of the same case. Code-pointers must have Eq values. Other 
atoms must be Eqn equal. A usually valid heuristic is that if 
two objects look the same if printed with the function Print, 
they are Equal. If one argument is known to be an atom, Equal is 
open-compiled as Eq- 


For example, if 
X:='(A BC); and Y:=X; then 
EQ(X,Y); is T 
EQ(X,'(A B C)); is NIL 
EQUAL(X,'(A B C)); is T 
EQ(1,1); is T 
EQ(1.0,1.0); is NIL 
EQN(1.0,1.0)3 is T 
EQN(1,1.0); is NIL 
EQUAL(0,0.0); is NIL 


LispEqual (U:any, V:any): boolean expr 


An alternate name for Equal for use in SYSLISP mode. 


Neq (U:any, V:any): boolean macro 
Not Equal. 
Ne (Usany,Vsany): boolean open-compiled, expr 


Not(U Eq V). 
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EqStr (U:zany,V:any): boolean expr 


Compare two strings, for exact (Case sensitive) equality. For 
case-INsensitive equality one must load the STRINGS module (see 
Section 8.7.1). EqStr returns T if U and V are Eq or if U and V 
are equal strings. 


EqCar (U:any,Vsany): boolean expr 
Tests whether Car U Eq V. If the first argument is not a pair, 
EqCar returns NIL. 


4.2.2. Predicates for Testing the Type of an Object 


Atom (Usany): boolean open-compiled, expr 


Returns T if U is not a pair. 


CodeP (U:any): boolean open-compiled, expr 


Returns T if U is a code-pointer. 


ConstantP (Usany): boolean expr 


Returns T if U is a constant (that is, neither a pair nor an id). 
Note that vectors are considered constants. 


[??? Should Eval U Eq U if U is a constant? ?77] 


FixP (Usany): boolean . open-compiled, expr 
Returns T if U is an integer. If BIG is loaded, this function 
also returns T for bignums. 

FloatP (Usany): boolean open-compiled, expr 


Returns T if U is a float. 


IdP (Usany): boolean open-compiled, expr 


Returns T if U is an id. 
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Null (Usany): boolean open-compiled, expr 
Returns Tif U is NIL. This is exactly the same function as Not, 
defined in Section 4.2.3. Both are available solely to increase 
readability. 

NumberP (U:zany): boolean open-compiled, expr 


Returns T if U is a number (integer or float). 


PairP (Usany): boolean open-compiled, expr 


Returns T if U is a pair. 


StringP (Uzany): boolean open-compiled, expr 


Returns T if U is a string. 


VectorP (U:any): boolean open-compiled, expr 


Returns T if U isa vector. 


4.2.3. Boolean Functions 

Boolean functions return NIL for "false"; anything non-NIL is taken to be 
true, although a conventional way of representing truth is as T. Note that 
T always evaluates to itself. NIL may also be represented as '(). The 
Boolean functions And, Or, and Not can be applied to any LISP type, and are 
not bitwise functions. And and Or are frequently used in LISP as control 
structures as well as Boolean connectives (see Section 9.1). For example, 
the following two constructs should give the same result: 


IF A AND B AND C THEN D; 
A AND B AND C AND D; 


Since there is no specific Boolean type in LISP and since every LISP 
expression has a value which may be used freely in conditionals, there is 
no hard and fast distinction between an arbitrary function and a Boolean 
function. However, the three functions presented here are by far the most 
useful in constructing more complex tests from simple predicates. 


Not (U:form): boolean open-compiled, expr 
Returns Tif U is NIL. This is exactly the same function as 


Null, defined in Section 4.2.2. Both are available solely to 
increase readability. 


oe) 
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And (LU:form]): extra-boolean open-compiled, fexpr 


And evaluates each U until a value of NIL is found or the end of 
the list is encountered. If a non-NIL value is the last value, 
it is returned; otherwise NIL is returned. Note that And called 
with zero arguments returns T. 


Or (LU:form]): extra-boolean open-compiled, fexpr 


U is any number of expressions which are evaluated in order of 
their appearance. If one is found to be non-NIL, it is returned 
as the value of Or. If all are NIL, NIL is returned. Note that 
if Or is called with zero arguments it returns NIL. 


4.3. Converting Data Types 


The following functions are used in interconverting data types. They are 
grouped according to the type returned. Numeric types may be 
interconverted using functions such as Fix and Float, described in Section 
Sees 


Intern (U:fid,string)): id expr 


Converts string to id. Intern searches the id-hash-table (or 
current id-hash-table if the package system is loaded) for an id 
with the same print name as U and returns the id on the 
id-hash-table if a match is found. Any properties and GLOBAL 
values associated with the uninterned U are lost. If U does not 
match any entry, a new one is created and returned. If U has 
more than the maximum number of characters permitted by the 
implementation (???), an error is signalled: 


#*###% Too many characters to INTERN 


[??? Rewrite for package system; include search path, global, 
local, intern, etc. See the Ids Chapter. ???] 


The maximum number of characters in any token is 5000. 


NewId (S:string): id expr 


Allocates a new uninterned id, and sets its print-name to the 
string S. The string is not copied. 
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Int2Id (I:integer): id expr 
Convert integer to id pointer; this refers to the I'th id in the 


id space. Since 0 ... 127 correspond to ASCII characters, Int2Id 
converts an ASCII code to the corresponding single character id. 


Id2Int (D:id): integer expr 


Returns the id space position of id as a LISP number. 


Sys2Int (U:s-integer): integer expr 


Convert a word-sized integer to a LISP number; space may have to 
be allocated from the heap if not in inum range. o 


Int2Sys (I:integer): s-integer expr 
Converts a tagged LISP integer to an untagged full-word 
s-integer. 

Id2String (D:id): string expr 
Get name from id space. Id2String returns the Print name of its 
argument as a string. This is not a copy, so destructive 
operations should not be performed on the result. See CopyString 
in Chapter 8. 


[??? Should it be a copy? ???] 


String2List (S:string): inum-list expr 


Creates a list of Length one plus Size(S), converting the ASCII 
characters into small integers. 


[??? What of 0/1 base for length vs length -1. What of the 
NUL char added ???] 
List2String (L:inum-list): string expr 


Allocates a string of the same Size as L, and converts inums to 
characters according to their ASCII code. 


[??? Check is 0 ... 127, and signal error ???] 
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String ([I:inum]): string nexpr 


Creates and returns a string containing all the inums given. 


Vector2String (V:vector): string expr 


Pack the small integers in the vector into a string of the same 
Size, using the integers as ASCII values. 


(22? check for integer in range 0 +... 127 ?2?] 


String2Vector (S:string): vector expr 


Unpack the string into a vector of the same Size. The elements 
of the vector are small integers, representing the ASCII values 
of the characters in S. 


Vector2List (V:vector): list expr 
Create a list of the same Size as V (i.e. of Length Upbv(Y)+1), 


copying the elements in order 0, 1, +..., Upbv(V). 


$ 


List2Vector (L:list): vector expr 


Copy the elements of the list into a vector of the same Size. 


Vector ([U:zany]): vector nexpr 


Creates and returns a vector containing all the Us given. 
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CHAPTER 5 
NUMBERS AND ARITHMETIC FUNCTIONS 


. Big Integers 5.1 
. Conversion Between Integers and Floats 5.2 

Arithmetic Functions 5.2 
Functions for Numeric Comparison 5.5 
. Bit Operations 5.6 


Most of the arithmetic functions in PSL expect numbers as arguments. In 


all cases an error occurs if the parameter to an arithmetic function is not 
a number: 


**ž%**ž An attempt was made to do ARITHMETIC on "XXX", which is not a 
number 


XXX is the name of the parameter at fault. Exceptions to the rule are 
noted. 


| 
The underlying machine arithmetic requires parameters to be either all 


integers or all floats. If a function receives mixed types of arguments, . 
integers are converted to floats before arithmetic operations are 


performed. The range of numbers which can be represented by an integer is 
different than that represented by a float. Because of this difference, a 
conversion is not always possible; an unsuccessful attempt to convert may 
cause an error to be signalled. 


5.1. Big Integers 
LOAD Big; redefines the basic arithmetic operations, including the 


logical operations, to permit arbitrary precision integer operations. This 
is not yet implemented on the VAX. 


Note that fixnums which are present before loading Big can cause 
problems. 


Most functions seem to work, including Fix and Float. 


PSL Manual 13 July 1982 Arithmetic Functions 
page 5.2 section 5.2 


5.2. Conversion Between Integers and Floats 


The conversions mentioned above can be done explicitly by the following 
functions. Other functions which alter types can be found in Section 4.3. 


Fix (U:znumber): integer expr 


Returns the integer which corresponds to the truncated value of 
U. The result of conversion must retain all significant porcions 


of U. If U is an integer it is returned unchanged. 


[??? Note that unless big is loaded, an float with value 
larger than 2**35-1 on the DEC-20 is converted into something 
strange but without any error message. Note how truncation 
works on negative numbers (always towards zero). ?77] 


Float (U:number): float expr 


The float corresponding to the value of the argument U is 


returned. Some of the least significant digits of an integer may 
be lost due to the implementation of Float. Float of float 


returns the number unchanged. If U is too large to e rea in 
float, an error occurs: 


**x*** Argument to FLOAT is too large 
[??? Only if big is loaded can one make an integer of value 
greater than 2**35.1, so without big you won't get this error 


message. The largest representable float is 
(2*62.-1)*(2**65) on the DEC-20. ???] 


5.3. Arithmetic Functions 


The functions described below handle arithmetic operations. Please note 
the remarks at the beginning of this Chapter regarding the mixing of 


argument types. 


Abs (U:number): number expr 


Returns the absolute value of its argument. 


Add1 (U:number): number expr 


Returns the value of U plus 1; the returned value is of the same 
type as U (integer or float). 


J 


J 


J 


a 
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Deer (U:form, [Xi:number]): number macro 


Part of the USEFUL package (LOAD USEFUL;). With only one 
argument, this is equivalent to 


SETF(U, SUB1 U); 
With multiple arguments, it is equivalent to 


SETF(U, DIFFERENCE(U, PLUS(X1, ..., Xn))) 


[1] load useful; 
NIL 

[2] Y:2'(1 5 7); 
(15 7) 

[3] Deer Car Y; 

0 


[4] Y; 

(057) 

[5] Decr (Cadr Y, 3, 4); 
-2 

[6] Y; 

(0 -2 7) 


Difference (U:number, V:number): number expr 


The value of U - V is returned. 


Divide (U:number, V:number): pair | expr 


Expt 


Incr 


The pair (quotient . remainder) is returned. The quotient part 
is computed by Quotient and the remainder by Remainder. An error 
occurs if division by zero is attempted: 


R#ER*X Attempt to divide by O in Divide 


(U:number, V:integer): number expr 


Returns U raised to the V power. A float U to an integer power V 
does not have V changed to a float before exponentiation. 


(U:form, [Xi:number]): number macro 


Part of the USEFUL package (LOAD USEFUL;). With only one 
argument, this is equivalent to 
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SETF(U, ADD1 U); 
With multiple arguments it is equivalent to 


SETF(U, PLUS(U, X1, ..., Xn)); 


Minus (U:number): number expr 


Returns -U. 


Plus ([U:number]): number macro 


Forms the sum of all its arguments. 


Plus2 (U:number, V:number): number expr 


Returns the sum of U and V. 


Quotient (U:number, V:number): number . expr 


The Quotient of U divided by V is returned. Division of two 
positive or two negative integers is conventional. If both U and 
V are integers and exactly one of them is negative, the value 
returned is the negative truncation of the Quotient of Abs U and 
Abs V. If either argument is a float, a float is returned which 
is exact within the implemented precision of floats. An error 
occurs if division by zero is attempted: 


¥X¥** Attempt to divide by 0O in QUOTIENT 


Recip (U:number): float expr `’ 


Recip converts U to a float if necessary, and then finds the 
inverse using the function Quotient. 


Remainder (U:number, V:number): number expr 


If both U and V are integers the result is the integer remainder 
of U divided by V. If either parameter is a float, the result is 
the difference between U and V*(U/V), all in float (probably 
0.0). If either number is negative the remainder is negative. 
If both are positive or both are negative the remainder is 
positive. An error occurs if V is zero: 


*EX*% Attempt to divide by O in REMAINDER 


L 


J 
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Sub1 (U:number): number , expr 


Returns the value of U minus 1. If U is a float, the value 
returned is U minus 1.0. 
Times ([U:number]): number macro 


Returns the product of all its arguments. 


Times2 (U:number, V:number): number expr 


Returns the product of U and V. 


5.4. Functions for Numeric Comparison 
The following functions compare the values of their arguments. Although 


most return a boolean quantity, note that Max, Min, and some others are 
extra-boolean, i.e. they return one of their arguments. For functions 


testing equality (or non-equality) see Section 4.2.1. 

Geq (U:any, V:any): boolean macro 
Returns T if U >= V, otherwise returns NIL. In RLISP, the symbol 
">=" can be used. 

GreaterP (U:number, V:number): extra-boolean l expr 
Returns U if U is strictly greater than V, otherwise returns NIL. 
In RLISP, the ~ symbol > can be used. 

Leg (U:number, V:number): boolean macro 


Returns T if U <= V, otherwise returns NIL. In RLISP, the symbol 
<= can be used. 


LessP (U:number, V:number): extra-boolean expr 


Returns U if U is strictly less than V, otherwise returns NIL. 
In RLISP, the symbol < can be used. 
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Max ([U:number]): number macro 


Returns the largest of the values in U (numeric maximum). If two 
or more values are the same, the first is returned. 


Max2 (U:number, V:number): number expr 


Returns the larger of U and V. If U and V are of the same value 


U is returned (U and V might be of different types). 


Min ([U:number]): number ; macro 


Returns the smallest (numeric minimum) of the values in U. If 


two or more values are the same, the first of these is returned. 


Min2 (U:number, V:number): number expr 


Returns the smaller of its arguments. If U and V are the same 
value, U is returned (U and V might be of different types). 


MinusP (U:any): extra-boolean expr 


Returns U if U is a number and less than 0. If U is not a number 
or is a positive number, NIL is returned. 


OneP (U:any): extra-boolean expr 


Returns U if U is a number and has the value 1 or 1.0. Returns 
NIL otherwise. 


ZeroP (U:any): extra-boolean expr 


Returns U if U is a number and has the value 0 or 0.0. Returns 
NIL otherwise. 


5.5. Bit Operations 


The functions described in this Section operate on the binary 
representation of the integers given as arguments. The returned value is 


an integer. 
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LAnd (U:integer, V:integer): integer expr 
Bitwise or logical And. Each bit of the result is independently 


determined from the corresponding bits of the operands according 
to the following table. 


U 0 0 1 1 
V 0 1 0 1 
Returned Value 0 0 0 1 
LOr (U:integer, V:integer): integer expr 


Bitwise or logical Or. Each bit of the result is independently 
determined from corresponding bits of the operands according to 
the following table. 


U 0 0 1 e N 
v 0 1 0 1 
Returned Value 0 1 1 1 
LNot (U:integer): integer expr 


Logical Not. Defined as (-U + 1) so that it works for bignums as 
if they were 2's complement. 


[?2?? need to clarify a bit more ?77] 


LXOr (U:integer, V:integer): integer expr 


Bitwise or logical exclusive Or. Each bit of the result is 
independently determined from the corresponding bits of the 
operands according to the following table. 


U 0 0 1 1 
Y 0 1 0 1 
Returned Value 0 1 1 0 
LShift (N:integer, K:integer): integer expr 


Shifts N to the left by K bits. The effect is similar to 
K 


multiplying by 2. It is an arithmetic shift. Negative values 
are acceptable for K, and cause a right shift (in the usual 


ed 


manner). > 


J 


E 
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CHAPTER 6 
IDENTIFIERS 
6.1. Introduction 5 
6.2. Fields of Ids A 
6.3. Identifiers and the Id-Hash-Table š 
6.4. Property List Functions ` 


6.4.1. Functions for Flagging Ids 

6.4.2. Direct Access to the Property Cell 
5. Value Cell Functions 
.6. Package System Functions 


o 
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6.1. Introduction 


In this Chapter ids are discussed. Ids are represented externally as a 
character string, typically alphanumeric. Internally they are converted 
into unique structures in a symbol-table with the aid of an id-hash-table. 
In PSL, ids are variables with values or names of functions and have 


property lists to store relationships between ids. PSL also provides a 


. package system, which gives the user a tree-structured id-hash-table. 


6.2. Fields of Ids 


An id is an item with an info field; the info field is an offset into a 
special id-space consisting of structures of 5 fields. The fields (items) 
are: 


print-name The print name points at a string of the characters of the 
identifier. ids begin with a letter or any character 


preceded by an escape character. They may contain letters, 
digits, and escaped characters. 


property-cell The property cell points at a property list in the heap to 


store flags and (indicator . value) pairs. Access is by 
means of the Flag, RemFlag, FlagP, Put, Get, and RemProp 
functions defined in Section 6.4. 


value-cell The value used by the Eval function for an id is stored in 


this field. A binding type determines how a value is 
attached to an identifier and can be either LOCAL, GLOBAL, 
or FLUID (see Chapter 10). The Global, GlobalP, Fluid, 
FluidP, and UnFluid functions are used to access the binding 
type. Access to values is by means of the ValueCell, Set. and 
SetQ functions defined later in this Chapter. 


function-cell An id may have a function or macro associated with it. 
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Access is by means of the PutD, GetD, and RemD functions 
defined in Section 10.1.2. 

package-cell An id usually exists on a structure called an id-hash-table 
(the "oblist" in older LISPs), which is used by Read to find 
a unique id if given an identifier character string. PSL 
optionally permits the use of a multiple package facility 
(multiple id-—hash-table or "multiple-oblist"). The package 
cell refers to the appropriate id-hash-table. Access to the 
id-hash-table is by means of Intern, Rem0b, Read and other 
functions defined in Chapters Y, 6, and 13. 


6.3. Identifiers and the Id-Hash-Table 


The following functions deal with identifiers and the id-hash-table. The 
id-hash-table is used by Read and similar functions to ensure that ids that 
have the same input characters refer to the same id (i.e. Eq). This 
process is called Intern-ing an id or string. 


Basic PSL currently provides a single id-hash-table; ids either are 
interned on this table or are un-interned. PSL provides all the "hooks" to 
permit a package system to be loaded as an option; certain functions are 
redefined in this process. If the .package system is loaded, a 
tree=structured id-hash-table can be created in which each level can be 
thought of as a smaller id-nash-table. If a new id or string is to be 
interned, it is searched for in the tree according to a specified rule. 


The character "\" is normally reserved in the basic Read-Table (see. 
Chapter 13) to make up multi-part names of the form "PackageName\LocallId". 
If the package system is loaded, the Intern process starts searching a path 
in a linked structure from "PackageName", itself an id accessible in the 
"CurrentPackage". The print-name is still "LocalId", but the additional 
package field in each id records "PackageName". Prini and Prin2 are 
modified to access this field in loading the package system. The root of 
the tree is the GLOBAL package, indicated by \. If the package system is 
loaded, the basic id-hash-table is made into the GLOBAL package. Thus MID 
is guaranteed in the root (in fact the pre-existing id-hash-table). More 
information is given in Section 6.6. 


(22? Explain further or at least more clearly. ???] 


Information on converting ids to other types can be found in Chapter 
13 and Section 4.3. 


J 


J 


J 
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J 
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GenSym (): id expr 


Creates an identifier which is not interned on the id-hash-table 
and consequently not Eq to anything else. The id is derived from 
a string of the form "G0O000", which is incremented upon each call 
to GenSym. 


[??? Is this interned or recorded on the NIL package ???] 


[222 Can we change the GenSym string ???] 


StringGensym (): string expr 


Similar to GenSym but returns a string instead of an id. 


RemOb (U:id): Utid expr 


If U is present on the current package search path it is removed. 


This does not affect U having properties, flags, functions and 
the like. U is returned. 


InternP (U:id): boolean a expr 


Test if an id is interned in the current search path. 


6.4. Property List Functions 


The property cell of an id usually points at a "property list". The list 
is used to quickly associate an id name with a set of entities; those 
entities are called "flags" if their use gives the id a boolean value, and 
"properties" if the id is to have an arbitrary attribute (an indicator with 
a property). 


Put (U:id, IND:id, PROP:any): any expr 


The indicator IND with the property PROP. is placed on the 
property list of the id U. If the action — of Put occurs, the 
value of PROP is returned. If either of U and IND are not ids 
the type mismatch error occurs and no property is placed. 


Get (Usid, IND:id): any expr 


Returns the property associated with indicator IND from the 
property list of U. If U does not have indicator IND, NIL is 
returned. (In older LISPs, Get could access functions.) Get 
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returns NIL if U is not an id. 


DefList (U:list, IND:id): list expr 


U is a list in which each element is a two-element list: 
(ID:ID PROP:ANY). Each id in U has the indicator IND with 


property y PROP placed on its property list by the Put function. 
The value of DefList is a list of the first elements of each 
two-element list. Like Put, DefList may not be used to define 
functions. 


EXPR PROCEDURE DEFLIST(U, IND); 
IF NULL U THEN NIL 
ELSE <<PUT(CAAR U, IND, CADAR U); 
CAAR U >> . DEFLIST(CDR U, IND); 


RemProp (U:id, IND:id): any expr 


Removes the property with indicator IND from the property list of 
U. Returns the removed property or NIL if there was no such 
indicator. 


RemPropL (U:id-list, IND:id): NIL expr 


Remove property IND from all ids in U. 


MapObl (FNAME:function): Undefined expr 


MapObl applies function FNAME to each id interned in the current 
LISP. 


6.4.1. Functions for Flagging Ids 
In some LISPs, flags and indicators may clash. In PSL, flags are ids and 
properties are pairs on the prop-list, so no clash occurs. 


Flag (U:id-list, V:id): NIL expr 
U is a list of ids. Flag flags each id with V; that is, the 
-effect of Flag is that for each id X in U, FlagP(X, V) has the 
value T. Both V and all the elements of U must be identifiers or 
the type mismatch error occurs. After Flagging, the id V appears 
on the property list of each id X in U after using Flag; that is, 
V becomes an element of the list Prop X;. However, flags cannot 
be accessed, placed on, or removed from property lists using 
normal property list functions Get, Put, -and RemProp. Note that 
if an error occurs during execution of fiag) , then some of the ids 
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on U may be flagged with V, and others may not be. 


FlagP (U:id, V:any): boolean expr 


Returns T if U has been flagged with V; otherwise returns NIL. 
Returns NIL if either U or V is not an ad, 


RemFlag (U:id-list, V:id): NIL expr 
Removes the flag V from the property list of each member of the 
list U. Both V and all the elements of U must be ids or the type 
mismatch error occurs. 


Flag1 (U:id, V:any): Undefined expr 


Give id U flag V. 


RemFlag1 (U:id, V:any): Undefined expr 
Remove a single flag. 

[??? Make Flag1 and RemFlag1 return single value. ???] 
6.4.2. Direct Access to the Property Cell 

Use of the following functions can destroy the integrity of the property 
list. Since PSL uses properties at a low level, care should be taken in 
the use of these functions. 
Prop (U:id): any expr 


Access the property list of U. 


SetProp (U:id, L:any): L:any expr 


Store item L as the property list of U. 


6.5. Value Cell Functions 


The contents of the value cell are usually accessed by Eval (Chapter 11) 
or ValueCell (below) and changed by Set or SetQ. 
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Set (EXP:id, VALUE:any): any expr 
EXP must be an identifier or a type mismatch error occurs. The 


effect of Set is replacement of the item bound to the identifier 
by VALUE. If the identifier is not a LOCAL variable or has not 


been declared GLOBAL, it is automatically declared FLUID with the 
resulting warning message: 
*** EXP declared FLUID 


EXP must not evaluate to T or NIL or an error occurs: 


***** Cannot change T or NIL 


SetQ (VARIABLE:id, VALUE:any): any fexpr 
SETQ(X, 1); 
is similar to 
SET ('X, 1); 
The value of the current binding of VARIABLE is replaced by the 
value of VALUE. One can use the symbol := to call this function 


in RLISP. SetQ now conforms to the Common LISP standard, 
allowing sequential assignment: 


(SETQ A 1 B 2) 
==> (SETQ A 1) 
(SETQ B 2) 
DeSetQ (U:any, V:any): V:any macro 
This is a function in "USEFUL" (Load USEFUL; in RLISP). DeSetQ 
is a destructuring SetQ. That is, the first argument is a piece 
of list structure whose atoms are all ids. Each is SetQ'd to the 
corresponding part of the second argument. For instance 


(DeSetQ (a (b) . e) '((1) (2) (3) 4)) 


SetQ's a to (1), b to 2, and e to ((3) 4). 


PSetQ ([VARIABLE:id, VALUE:any]): Undefined macro 
Part of the USEFUL package (LOAD USEFUL;). 
(PSETQ VAR1 VAL1 VAR2 VAL2 ... VARn VALn) 


SetQ's the VAR's to the corresponding VAL's. The VAL's are all 


aJ 
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SetF 


evaluated before any assignments are made. That is, this is a 
parallel SetQ. 

({LHS:form, RHS:any]): RHS:any 

SetF is redefined on loading USEFUL. The description below is 
for the resident SetF. SetF provides a method for assigning 
values to expressions more general than simple ids. 


For example: 


(SETF (CAR X) 2) 
==> CAR X ts 2; 


is equivalent to 


(RPLACA X 2) 


In general, SetF has the form 
(SetF LHS RHS) 
in which LHS is the "left hand side" to be assigned to and RHS is 


evaluated to the value to be assigned. LHS can be one of the 
following: 


id SetQ is used to assign a value to the 
id. 
(Eval expression) Set is used instead of SetQ. In 


effect, the "Eval" cancels out the 
"Quote" which would normally be used. 


(Value expression) Is treated the same as Eval. 
(Car pair) RplacA is used to store into the Car 
"field". 
(Cdr pair) . e RplacD is used to store into the Cdr 
A "field". 
(Get V vector) os PutV is used to store into the 


-appropriate location. 

(Indx "indexable object") SetIndx is used to store into the 
an er object. 

(Sub vector) SetSub is used to store into the 
appropriate subrange of the vector. 


Note that if the LHS is a ar pair) or (Cdr pair), SetF returns 
the modified pair instead the RHS, because SetF uses RplacA 
and RplacD in these cases. 


page 6.7 
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On the DEC-20, loading USEFUL brings in declarations to SetF 
about Caar, Cadr, ... Cddddr. This is rather handy with 
constructor/selector macros. For instance, if FOO is a selector 
which maps to Cadadr, 

(SETF (FOO X) Y) 
works; that is, it maps to something which does a 


(RPLACA (CDADR X) Y) 


and then returns X. 


PSetF ([LHS:form, RHS:any]): Undefined macro 


Part of the USEFUL package (LOAD USEFUL;). PSetF does a SetF in 
parallel: i.e. it evaluates all the right hand sides (RHS) before 
assigning any to the left hand sides (LHS). 


MakeUnBound (U:id): Undefined expr 


Make U an unbound id by storing a "magic" number in the value 
cell. 


ValueCell (U:id): any expr 


Safe access to the value cell of an id. If U is not an id a type 
mismatch error is signalled; if U is an unbound id, an unbound id 
error is signalled. Otherwise the current value of U is 
returned. [See also the Value and LispVar functions, described 
in Chapter 21, for more direct access]. 


[??? Define and describe General Property LISTs or hash-tables. See 
Hcons. ???] 


6.6. Package System Functions 


The following fluid variables are managed by the package system, which is 
currently optional (LOAD PACKAGE;). 


\CURRENTPACKAGE!* (Initially: Global) global 


This is the start of the search path if interning. 
\Current Package! * is rebound in the token scanner on encountering 
a myn a 


L 


) 


zz 
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\PACKAGENAMES!* (Initially: (Global)) global 


List of ALL package names currently created. 

Our current package model uses a set of general path functions that 
access functions specific to each level of the id-hash-table tree to do 
various things: "Localxxxx(s)" and "Pathxxxx(s)" in which "xxxx" is one of 
the set (InternP, Intern, RemOb, MapObl). By storing different functions, 


each package may have a different structure and associated functions. The 
current implementation of a package uses a vector 


[Name Father GetFn PutFn RemFn MapFn] 
stored under the indicator 'Package on the PackageName id. 


A simple bucket id-hash-table can also be used for experiments, or the 
user can build his own. As far as possible, each function checks that a 
legal package is given before performing the operation. 


[??? Should we have a package Tag ??7] 
The following functions should be used. 


\CreatePackage (NAME:id, FATHERPACKAGE:id): id expr 
This creates a convenient size id-hash-table, generates the 
functions to manage it for this package, and links the new 
package to the FATHERPACKAGE so that path searches for ids are 
required. 


\Set Package (NAME:id): id expr 


Selects another package such as GLOBAL\. 


XPathInternP (S:{id, string}): boolean expr 


Searches from CurrentPackage!* to see if S is interned. 


\PathIntern (S:(fid, string}): id expr 


Look up or insert an id. 
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\PathRemob (S:fid, string)): id | expr 


Remobs, puts in NIL package. 


\PathMapObl (F:function): NIL expr 


Applies F to ALL ids in path. 


\LocalInternP (S:fid, string)): boolean expr 


Searches in CURRENTPACKAGE!*, 


\LocalIntern (S:{id, string)): id expr 


Look up or insert in CURRENTPACKAGE!* (forces ids uninterned in 
CURRENTPACKAGE!* into CURRENTPACKAGE!*) , 


\LocalRemob (S:{id, string}): id expr 


Remobs, puts in NIL package. 


\LocalMapObl (F:function): NIL expr 
“Applies F to ALL ids in (CurrentPackage!*). 


Note that if a string is used, it CANNOT include the \. Also, since most 
ids are "RAISED" on input, be careful. 


Current intern, etc. are \PathIntern, etc. 


Several restrictions are placed on the use of packages when compiled. 
Since it is a loaded module and not integrated with the basic PSL system, 
all ids in the compiled package are Interned in Global\ before they are 
defined. This requires a slightly more complex loading system for 
packages. Names and function ids which conflict with names in Global\ (or 
other packages in the path) must be forced into the id-hash-table of the 
desired package. The package is compiled WITHOUT the package module 
loaded. 


In addition, if a function call must be issued for a function which has 
been redefined in the package the function name must be changed. When 
PACKAGE has been integrated with Fasl and PSL, it will be sufficient to 
prefix the function name with the package name (e.g. Global\Print). 
Currently, one must actually change the function name (e.g. Global!.Print). 


J 


od 
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As an example, a small package which redefines the system function Print 
is shown. The assumed file name is PrintPack.red. 


symbolic procedure GetFieldFn(relation,field); 
slotdescslotfn 
cdr assoc(field,dsdeseslotalist getdefstruct relation); 


symbolic fexpr procedure Print(args); 

begin scalar fields; 
fields := Get(car args,'Fields); 
ForEach elem in eval car args do 

Global!.Print (ForEach field in fields Collect 
apply(GetFieldFn(car args,field),'list elem)); 

return car args 

end; 


This package would be compiled as follows (immediately after entering 
RLISP): 


faslout "PrintPackage"; 
in "PrintPack.red"$ 
faslend; 

quit; 


This package would be loaded as follows (immediately after entering 
RLISP): 


load '(defstruct package); 
CopyD('Global!.Print, Print) ; 
<<\CreatePackage('PrintPack, 'Global); 
\Set Package('PrintPack) ; 
Local Intern 'Print>>; 
faslin "PrintPack.b"; 
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CHAPTER 7 
LIST STRUCTURE 


7.1. Introduction to Lists and Pairs 
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7.1. Introduction to Lists and Pairs 


The pair is a fundamental PSL data type, and is one of the major 
attractions of LISP programming; it provides the ability to easily build 
and manage binary tree objects. Automatic storage management in PSL 
enables the user to concentrate on the programming task. Trees built of 
pairs are used to do sorting and to represent parse trees and complex 
hierarchical relationships. 


A pair consists of a two-item structure. In PSL the first element is 
called the Car and the second the Cdr; in other LISPs, the physical 
relationship of the parts may be different. An illustration of the tree 
structure is given below as a Box diagram; the Car and the Cdr are each 
represented as a portion of the box. 


it Car { Cdr !! 


As an example, a tree written as ((A . B) . (C . D)) in Dot notation is 
drawn as below in Box notation. 
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The box diagrams are tedious to draw, so Dot notation is normally used. 
Note that a space is left on each side of the . to ensure that pairs are 
not confused with floats. Note also that in RLISP a dot may be used as the 
infix operator for the function Cons, as in the expression x := 'y . 'z;3, 
or as part of the notation for pairs, as in the expression x := '(y . 2); 


(see Section 3.3.3). 


An important special case occurs frequently enough that it has a special 
notation. This is a list of items, terminated by convention with the id 
NIL. The dot and surrounding parentheses are omitted, as well as the 
trailing NIL. Thus 


(A. (B. (C . NIL))) 
can be represented in list notation as 


BD 


7.2. Basic Functions on Pairs 


The following are elementary functions on pairs. All functions in this 
Chapter which require pairs as parameters signal a type mismatch error if 
the parameter given is not a pair. 


Cons (Usany, V:any): pair expr 


Returns a pair which is not Eq to anything else and has U as its 
Car part and V as its Cdr part. in RLISP syntax the dot, ".", is 
an infix operator meaning Cons. Thus (A. (B. fn C) . D) is 
equivalent to Cons (A, Cons (Cons (B, fn C), D)). See Section 
3.3.3 for more discussion of how dot is read. 


J 


J 
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Car (U:pair): any 
The left part of U is returned. A type 
U is not a pair. Car Cons (a, b) ==> a. 
Cdr (U:pair): any 


The right part of U is returned. A type 
U is not a pair. Cdr Cons (a, b) ==> b. 


The composites of Car and Cdr are supported 
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open-compiled, expr 


mismatch error occurs if 


open-compiled, expr 


mismatch error occurs if 


up to four levels. 


Car Cdr 
Caar Cdar Cadr ~  Cddr 
Caaar Cdaar Cadar Cddar Caadr Cdadr Caddr Cdddr 
Caaaar Cadaar Caadar Caddar Caaadr Cadadr Caaddr Cadddr 
Cdaaar Cddaar Cdadar Cdddar Cdaadr Cddadr Cdaddr Cddddr 


These are all exprs of one argument. They may return any type 
and are generally open-compiled. An example of their use is that 


Cddar p is equivalent to Cdr Cdr Car p. 


As with Car and Cdr, a 


type mismatch error occurs if the argument does not possess the 


specified component. 


As an alternative to employing chains of CxxxxR to obscure depths, 


particularly in extracting elements of a list, 


consider the use of the 


functions First, Second, Third, Fourth, or Nth (Section 7.3.1), or possibly 


even the Defstruct package (Section 18.6). 


NCons (U:any): pair 


Equivalent to Cons (U, NIL). 


XCons (U:any, V:any): pair 


Equivalent to Cons (V, U). 


Copy (X:any): any 


Copy all pairs in an S-expression; 


open-compiled, expr 


open-compiled, expr 


expr 


this does not copy each 


element of vectors, etc. See TotalCopy in Section 8.5. 


See Chapter 8 for other relevant functions. 


The following functions are known as "destructive" functions, because 
they change the structure of the pair given as their argument, and 
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consequently change the structure of the object containing the pair. They 


are most frequently used for various "efficient" functions (e.g. the 
non-copying ReverseIP and NCone functions, and destructive DeleteIP) and to 
build structures that have deliberately shared sub-structure. They are 
also capable of creating circular structures, which create havoc with 
normal printing and list traversal functions. Be careful using them. 


RplacA (U:pair, V:any): pair open-compiled, expr 
The Car portion of the pair U is replaced by V. If pair U is 
(a . b) then (V . b) is returned. A type mismatch error occurs 
if U is not a pair. 

RplacD (U:pair, V:any): pair open-compiled, expr 
The Cdr portion of the pair U is replaced by V. If pair U is 
(a . b) then (a . V) is returned. A type mismatch error occurs 
if U is not a pair. 

RplacW (A:pair, B:pair): pair | expr 
Replace whole pair. 


RPLACA(RPLACD(A, CDR B), CAR B) 


[??? Should we add some more functions here someday? Probably the 
RLISP guys that do arbitrary depth member type stuff. ?77] 


7.3. Functions for Manipulating Lists 


The following functions are meant for the special pairs which are lists, 
as described in Section 7.1. 


[??? Make some mention of mapping with FOR...COLLECT and such like. 
222] 


7.3.1. Selecting List Elements 


First (L:pair): any macro 


A synonym for Car L; 
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Second (L:pair): any macro 
A synonym for Cadr L. 

Third (L:pair): any macro 
A synonym for Caddr L. 

Fourth (L:pair): any macro 
A synonym for Cadddr L. 

Rest (L:pair): any macro 
A synonym for Cdr L. 

LastPair (L:pair): any expr 


Last pair of alist. It is often useful to think of this as a 
pointer to the last element for use with destructive functions 
such as RplacA. Note that if L is atomic a type mismatch error 
occurs. 


EXPR PROCEDURE LASTPAIR L; 
IF NULL REST L THEN L 
ELSE LASTPAIR REST L; 


LastCar (L:any): any 


Returns the last element of the list L. A type mismatch error 
results if L is not a list. Equivalent to First LastPair L. 


Nth (L:pair, N:integer): any 


PNth 


Returns the Nth element of the list L. If L is atomic or 
contains fewer than N elements, an out of range error occurs. 
Equivalent to First PNth (L, N). 


(L:list, N:integer): any 


Returns list starting with the Nth element of a list L. Note 
that it is often useful to view this as a pointer to the Nth 


element of L for use with destructive functions such as RplacA. 
If L is atomic or contains fewer than N elements, an out of range 


error occurs. 


expr 


expr 


expr 
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EXPR PROCEDURE PNTH(L,N); 


IF N <= 1 THEN L 
ELSE NTH(CDR L,N-1); 


7.3.2. Membership and Length of Lists 


Member (A:any, L:list): extra-boolean expr 


Returns NIL if A is not Equal to some top level element of list 


L; otherwise it returns the remainder of L whose first element is 
A. 


EXPR PROCEDURE MEMBER(A,L); 
IF NULL L THEN NIL 
ELSE 1F A = FIRST L THEN L 
ELSE MEMBER(A,REST L); 


MemQ (A:any, B:list): extra-boolean expr 
Same as Member, but an Eq check is used for comparison. 
EXPR PROCEDURE MEMQ(A, L); 
IF NULL L THEN NIL 
ELSE IF A EQ FIRST L THEN L- 
ELSE MEMQ(A, REST L); 
Length (X:any): integer expr 
The top level length of the list X is returned. 
EXPR PROCEDURE LENGTH(X); 


IF ATOM X THEN O 
ELSE LENGTH REST X + 1; 


7.3.3. Constructing, Appending, and Concatenating Lists 
List ([U:any]): list fexpr 


Construct a list of the evaluated arguments. A list of the 
evaluation of each element of U is returned. 


Append (U:list, V:list): list expr 


Returns a constructed list in which the last element of U is 
followed by the first element of V. The list U is copied, but V 


yr) 


ay 
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EXPR PROCEDURE APPEND(U, V); 
IF NULL U THEN V 
ELSE CAR U . APPEND(CDR U, V); 


NCone (U:list, V:list): list 


Destructive version of Append. Concatenates V to U without 
copying U. The last Cdr of U is modified to point to V. See the 
warning on page 7.3 about the use of destructive functions, 


EXPR PROCEDURE NCONC(U,V); 
IF NULL U THEN V 
ELSE << RPLACD(LASTCDR U,V); 
U >>; 


ACone (U:list, V:any): list 


Destructively adds element V to the tail of list U. 


LCone (PTR:list, ELEM:list): list 


Effectively NCone, but avoids scanning from the front to the end 
of PTR for the RPLACD(PTR, ELEM) by maintaining a pointer to end 
of the list PTR. PTR is (list . LastPair list). Returns updated 
PTR. PTR should be initialized to NIL . NIL before calling the 
first time. Used to build lists from left to right. 


TCone (PTR:list, ELEM:any): list 


Effectively AConc, but avoids scanning from the front to the end 
of PTR for the RPLACD(PTR, List(ELEM)) by maintaining a pointer 
to end of the list PTR. PTR is (list . LastPair list). Returns 
updated PTR. PIR should be initialized to NIL. NIL before 
calling the first time. Used to build lists from left to right. 


Adjoin (ELEMENT:any, SET:list): list 


Add ELEMENT to SET if it is not already on the top level. Equal 
is used to test for equality. 


AdjoinQ (ELEMENT:any, SET:list): list 


Ad join using Eq for the test whether ELEMENT is already in SET. 


expr 


expr 


expr 


expr 


expr 


expr 


PSL Manual 13 July 1982 List Structure 
page 7.8 section 7.3 


7.3.4. Lists as Sets 


Union (X:list, Y:list): list expr 


Set union. 


UnionQ (X:list, Y:list): list expr 


Eq version of Union. 


InterSection (U:list, V:list): list expr 


Set interSection. 


InterSectionQ (U:list, V:list): list expr 
Eq version of Xn. 


7.3.5. Deleting Elements of Lists 
Note that functions with names of the form xxxIP indicate that xxx is 


done InPlace. 


Delete (Usany, V:list): list expr 
Returns V with the first top level occurrence of U removed from 
it. That portion of V before the first occurrence of U is 
copied. 


EXPR PROCEDURE DELETE(U,V); 
IF NULL V THEN NIL 
ELSE IF FIRST V = U THEN REST V 
ELSE FIRST V . DELETE(U, REST V); 


Del (F:function, U:any, V:list): list expr 


Generalized Delete function with F as the comparison function. 


DeletIP (U:any, V:list): list expr 


Destructive Delete; modifies V using RplacD. Do not depend on V 
itself correctly referring to list. 
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DelQ (U:any, V:list): list 


Delete U from V, using Eq for comparison. 


DelQIP (Usany, V:list): list 


Destructive version of DelQ; see DeletIP. 


Delete first (U . xxx) from V, using Eq to check equality with U. 


Destructive DelatQ. 


List2Set (SET:list): list 


Remove redundant elements from the top level of SET using Equal. 


List2SetQ (SET:list): list 


Remove redundant elements from the top level of SET using Eq. 
7.3.6. List Reversal 


Reverse (U:list): list 


Returns a copy of the top level of U in reverse order. 


expr 


expr 


expr 


expr 


expr 


expr 


expr 


expr 


expr 
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EXPR PROCEDURE REVERSE(U); 
BEGIN SCALAR W; 


WHILE U DO << W := CAR U . W; 
U := CDR U >>; 
RETURN W 
END; 
ReversIP (U:list): list expr 


Destructive Reverse. 


7.4. Comparison and Sorting Functions 


The module GSort (use LOAD GSORT) contains a number of general sorting 
functions and associated key comparison functions. The key comparison 
functions are given two objects to compare, and return NIL if they are not 
in correct order. The package defines the following SortFns: 


NumberSortFn (N1:number, N2:number): boolean expr 


Numeric comparison N1 <= Ne. 


StringSortFn (Si:string, S2:string): boolean expr 


Compares elements of the strings using ASCII collating code. 
Case is currently observed, but a case-folding version will be 
added. If the characters are identical then the shorter string 
is first in the collating order. 


IdSortFn (D1:id, D2:id): boolean expr 


Calls StringSortFn on the print names of the D1 and D2. 


AtomSortFn (X1:atom, X2:atom): boolean expr 


Sorts numbers ahead of ids and ids ahead of strings. Uses the 
above functions if types are same. 


The general sorting functions expect a SortFn (which MUST be an id) of 
the above type. 


L 


E 


J 


J 
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GSortP (LST:list, SORTFN:id): boolean expr 


Returns T if the list is sorted according to the SORTFN. 


GSort (LST:list, SORTFN:id): list expr 


Does a tree sort of LST, using SORTFN to compare elements. 


GMergeSort (LST:list, SORTFN:id): list expr 


Does a Merge sort of LST using SORTFN for comparison. Currently, 
GSort is often fastest, but GMergeSort is more stable. 


[??? Its major time seems to be in splitting the original 
list. 2777] 


Example: To sort a list of ids call GSort(Dlist, 'Idsortfn) or 
GSort(Dlist, 'IDe2) for faster sort. 


To sort a list of records (e.g. pairs), the user must define a comparison 
function. E.g. to sort LP, a List of dotted pairs (Number . Info), define 


PROCEDURE NPSORTFN(P1,P2); 
NUMBERSORTFN(CAR P1, CAR P2); 


` then execute GSort(LP, 'NPSortfn); 


See "PU:Gsort.Red" for the code and further ideas. 


7.5. Functions for Building and Searching A-Lists 


Assoc (U:any, V:a-list): {pair, NIL} expr 
If U occurs as the Car portion of an element of the a-list V, the 
pair in which U occurred is returned, else NIL is returned. 
Assoc might not detect a poorly formed a-list so an invalid 
construction may be detected by Car or Cdr. 
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EXPR PROCEDURE ASSOC(U, V); 
IF NULL V THEN NIL 
ELSE IF ATOM CAR V THEN 
ERROR(000, LIST(V, 
"is a poorly formed alist")) 
ELSE IF U = CAAR V THEN CAR V 
ELSE ASSOC(U, CDR V); 


Atsoc (Ri:sany, R2:any): any expr 


Scan R2 for pair with Car Eq R1. Eq version of Assoc. 


Ass (F:function, Usany, V:a-list): {pair, NIL} expr 
Ass is a generalized Assoc function. F is the comparison 
function. 

SAssoc (U:any, V:a-list, FN:function): any expr 


Searches the a-list V for an occurrence of U. If U is not in the 
a-list, the evaluation of function FN is returned. 


EXPR PROCEDURE SASSOC(U, V, FN); 
IF NULL V THEN FN() 
ELSE IF U = CAAR V THEN CAR V 
ELSE SASSOC(U, CDR V, FN); 


Pair (U:list, V:list): a-list : expr 


U and V are lists which must have an identical number of 
elements. If not, an error occurs. Returned is a list in which 
each element is a pair, the Car of the pair being from U and the 
Cdr being the corresponding element from V. 


EXPR PROCEDURE PAIR(U, V); 
IF AND(U, V) THEN (CAR U . CAR V). 
PAIR(CDR U, CDR V) 
ELSE IF OR(U, V) THEN ERROR(000, 
"Different length lists in PAIR") 
ELSE NIL; 


J 


L 


J 
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7.6. Substitutions 


Subst (U:any, V:any, W:any): any expr 


Returns the result of substituting U for all occurrences of V in 
W. Copies all of W which is not replaced by U. The test used is 
Equal. 


EXPR PROCEDURE SUBST(U, V, W); 
IF NULL W THEN NIL 
ELSE IF V = W THEN U 
ELSE IF ATOM W THEN W 
ELSE SUBST(U, V, CAR W) . SUBST(U, V, CDR W); 


SubstIP (U:any, V:any, W:any): any expr 


Destructive Subst. 


SubLis (X:a-list, Y:any): any expr 
This performs a series of Substs in parallel. The value returned 
is the result of substituting the Cdr of each element of the 
a-list X ‘for every occurrence of the Car part of that element in 


EXPR PROCEDURE SUBLIS(X, Y); 
IF NULL X THEN Y 
ELSE BEGIN SCALAR U; 
U := ASSOC(Y, X); 
RETURN IF U THEN CDR U 
ELSE IF ATOM Y THEN Y 
ELSE SUBLIS(X, CAR Y) . 
SUBLIS(X, CDR Y) 
END; 


SublA (Usa-list, V:any): any expr 


Eq version of SubLis; replaces atoms only. 
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CHAPTER 8 
STRINGS AND VECTORS 
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8.1. Vector-Like Objects 


In this Chapter, LISP strings, vectors, word-vectors, halfword-vectors, 
and byte-vectors are described. Each may have several elements, accessed 
by an integer index. For convenience, members of this set are referred to 
as x-vectors. X-vector functions also apply to lists. Currently, the 
index for x-vectors ranges from 0 to an upper limit, called the Size or UpB 
(upper bound). Thus an x-vector X has 1 + Size(X) elements. Strings index 
from 0 because they are considered to be packed vectors of bytes. Bytes 
are 7 bits on the DEC-20 and 8 bits on the VAX. 


[??? Note that with new integer tagging, strings are "packed" words, 
which are special cases of vectors. Should we add byte-vectors too, so 
that strings are different print mode of byte vector 222] 

[??? Size should probably be replaced by UPLIM or UPB. 2772] 

In RLISP syntax, X[i]; may be used to access the i'th element of an 
x-vector, and Xlil:=y; is used to change the i'th element to y. These 
functions correspond to the LISP functions Indx and SetIndx. 

[??? Change names to GetIndex, PutIndex ?77] 


For functions which change an object from one data type to another, see 
Section 4.3. 


8.2. Strings 


A string is currently thought of as a Byte vector, or a packed integer 


vector, with elements that are ASCII characters. A string has a header 


containing its length and perhaps a tag. The next M words contain the 0 
eee Size characters, packed as appropriate, terminated with at least 1 
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NULL. On the DEC-20, this means that strings have an ASCIZ string starting 

in the second word. (ASCIZ strings are NULL terminated.) 

Make!-String (UPLIM:integer, INITVAL:integer): string expr 
Construct string with UPLIM + 1 elements, each initialized to the 
ASCII code INITVAL. 

MkString (UPLIM:integer, INITVAL:integer): string expr 


An old form of Make!-String. 


String ([ARGS:integer]): string nexpr 
Create string of elements from a list of ARGS. 


[??? Should we check each arg in 0 ... 127. What about 128 
- 255 with 8 bit vectors? ?77] 


CopyStringToFrom (NEW:string, OLD:string): NEW:string expr 
Copy all characters from OLD into NEW. This function is 
destructive. 

CopyString (S:string): string expr 


Copy to new heap string, allocating space. 


[??? Should we add GetS, PutS, UpbS, ete ?77] 


8.3. Vectors 


A vector is a structured entity in which random item elements may be 
accessed with an integer index. A vector has a single dimension. Its 
maximum size is determined by the implementation and available space. A 
suggested input/output "vector notation" is defined (see Chapter 13). 


GetV (V:vector, INDEX:integer): any expr 
Returns the value stored at position INDEX of the vector V. The 
type mismatch error may occur. An error occurs if the INDEX does 


not lie within 0 ... UPBV(V) inclusive: 


**** INDEX subscript is out of range 
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A similar effect may be obtained in RLISP by using VLINDEX];. 

MkVect (UPLIM:integer): vector expr 


Defines and allocates space for a vector with UPLIM + 1 elements 
accessed as 0 ... UPLIM. Each element is initialized to NIL. An 
error occurs if UPLIM is < 0 or if there is not enough space for 


a vector of this size: 


#44424 A vector of size UPLIM cannot be allocated 


Make!-Vector (UPLIM:integer, INITVAL:integer): vector expr 
Like MkVect but each element is initialized to INITVAL. 

PutV (V:vector, INDEX:integer, VALUE:any): any expr 
Stores VALUE in the vector V at position INDEX. VALUE is 
returned. The type mismatch error may occur. If INDEX does not 
lie in 0 ... UPBV(V), an error occurs: 

##2%% INDEX subscript is out of range 

A Similar effect can be obtained in RLISP by typing in 
' VC INDEX]:=VALUE;. It is important to use square brackets, i.e. 

Woy, - 

UpbV (Usany): {NIL, integer} expr 
Returns the upper limit of U if U is a vector, or NIL if it is 
not. 

Vector (L[ARGS:any]): vector nexpr 
Create vector of elements from list of ARGS. The vector has N 
elements, i.e. Size = N - 1, in which N is the number of ARGS. 

CopyVectorToFrom (NEW:vector, OLD:vector): NEWs:vector expr 


Move elements, don't recurse. 


[ 2?2?Check size compatibility? ] 
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CopyVector (V:vector): vector expr 
Copy to new vector in heap. 


The following functions can be used after LOADing FAST!-VECTOR; 


IGetV (): | expr 


Used the same way as GetV. 


IPutV (): | expr 


Fast version of PutV. 


ISizeV (): expr 


Fast version of UpbV. 


ISizeS (): expr 


Fast version of Size. 


8.4. Word Vectors: 

Word-vectors or we-vectors are vector-like structures, in which each 
element is a "word" sized, untagged entity. This can be thought of. as a 
special case of fixnum vector, in which the tags have been removed. 
Make!-Words (): Word-Vector expr 

Defines and allocates space for a Word-Vector with UPLIM + 1 
elements, each initialized to INITVAL. 

Make!-Halfwords (): Halfword-Vector expr 
Defines and allocates space for a Halfword-vector with UPLIM + 1 
elements, each initialized to INITVAL. 

Make!-Bytes (): Byte-vector expr 


Defines and allocates space for a Byte-Vector with UPLIM + 1 
elements, each initialized to INITVAL. 


C 


J 


J 
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[??? Should we convert elements to true integers when accessing ???] 


[??? Should we add GetW, PutW, UpbW, ete 777] 


8.5. General X-Vector Operations 


Size (X:x-vector): integer | expr 


Size (upper bound) of x-vector. 


Indx (X:x-vector, Isinteger): any expr 
Access the I'th element of an x-vector. 
[??? Rename to GetIndex, or some such ???] 


Generates a range error if I is outside the range 0 ... Size(X): 


*+%* Index is out of range 


SetIndx (X:x-vector, Isinteger, A:any): any expr 
Store an appropriate value, A, as the I'th element of an 
x-vector. Generates a range error if I is outside the range 
0. ..Size(X): 


#2#2#% Index is out of range 


Sub (X:x-vector, Il:integer, I2:integer): x-vector expr 


Extract a subrange of x-vector, starting at Il, producing a new 
x-vector of Size 12. 


SetSub (X:x-vector, Il:integer, I2:integer, Y:x-vector): x-vector expr 


Store subrange of Y of size 12 into X starting at I1. 


SubSeq (X:x-vector, LO:integer, HI:integer): x-vector expr 


Returns an x-vector of Size HI-LO-1, beginning with the element 
of X with index LO. For example, 
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A:="[0 12345 6]; 
SUBSEQ(A, 4, 6); 


returns 


[4 5] 


Y must be of Size HI-LO-1; it must also be of the same type of 
x-vector as X. Elements LO through HI-1 in X are replaced by 
elements 0 through Size(Y) of Y. Y is returned and X is changed 
destructively. 


RLISP 

[Keeping rlisp] 

PSL 3.0 Rlisp, 1-Jun-82 
[1] as="0123456"; 
"0123456" 

[2] b:="abed"; 

"abed" 

[3] setsubseq(a,3,7,)); 
nabed" 

[4] a; 

"012abcd" 

[5] b; 

"abed" 


Concat (X:x-vector, Y:x-vector): x-vector expr 


Concatenate 2 x-vectors. Currently they must be of same type. 


[2227 Should we do conversion to common type ???] 


TotalCopy (S:any): an expr 
Unique copy of entire structure. 


See also Chapter 7 for copying functions. 


8.6. Arrays 

Arrays do not exist in PSL as distinct data-types; rather an array macro 
package will be available to declare and manage multi-dimensional arrays of 
items, characters and words, by mapping them onto single dimension vectors. 


[??? What operations, how to map, and what sort of checking ???] 


L 


J 


J 


E 


J 
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8.7. Common LISP String Functions 

A Common LISP compatible package of string and character functions nas 
been implemented in PSL, obtained by LOADing STRINGS. The following 
functions are defined, from Chapters 13 and 14 of the Common LISP 
manual [Steele 81]. Char and String are not defined because of other 
functions with the same name. 


[?2?? More documentation on these functions will be provided. 777] 
The following functions are present for compatibility. 


Standard!-CharP (C:character): boolean expr 


Non-control character. 


GraphicP (C:character): boolean expr 


Printable character. 


String!-CharP (C:character): boolean l expr 


A character that can be an element of a string. 


AlphaP (C:character): boolean expr 


An alphabetic character. 


UpperCaseP (C:character): boolean expr 


An upper case letter. 


LowerCaseP (C:character): boolean expr 


A lower case letter. 


BothCaseP (C:character): boolean expr 


Same as AlphaP. 
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DigitP (C:character): boolean expr 


A digit character (optional radix not supported). 


AlphaNumericP (C:character): boolean expr 


A digit or an alphabetic. 


Char!= (Cl:character, C2:character): boolean expr 


Strict character comparison. 


Char!-Equal (Ci:character, C2:character): boolean expr 


Similar character objects; case, font and bits are ignored. 


Char!< (C1:character, C2:character): boolean expr 


Strict character comparison. 


Char! > (Cl:character, C2:character): doolean i expr 


Strict character comparison. 


Char!-LessP (C1:character, C2:character): boolean expr 


Ignore case and bits for Char<. 


Char!-GreaterP (Cischaracter, C2:character): boolean expr 


Ignore case and bits for Char>. 


Char!-Code (C:character): character expr 


Character to integer conversion. 


Char!-Bits (C:character): integer expr 


Bits attribute of a character. Returns 0. 
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Char! -Font (C:character): integer expr 


Font attribute of a character. Returns 0. 


Code!-Char (I:integer, BITS:integer): extra-boolean expr 


Integer to character conversion, optional bits, font ignored. 


Character (C:character, BITS:integer, FONT:integer): extra-boolean expr 


Character plus bits and font, which are ignored. 


Char!-UpCase (C:character): character expr 


Raise a character. 


Char!-DownCase (C:character): character expr 


Lower a character. 


Digit!-Char (C:character): integer o expr 
Convert character to digit (optional radix, .bits, font [not 
implemented yet]). i 

Char!-Int (C:character): integer expr 


Convert character to integer. 


Int!-Char (I:integer): character expr 


Convert integer to character. 


RplaChar (S:string, I:integer, C:character): character expr 
Store a character C in a string S at position I. 


The string functions follow. 


String!= (Si:string, S2:string): boolean expr 


Compare two strings S1 and s2 (substring options not 
implemented). 
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String!-Equal (Si:string, S2:string): boolean expr 


Compare two strings S1 and S2, ignoring case, bits and font. 


String!< (Sisstring, S2:string): extra-boolean expr 


Lexicographic comparison of strings. 


String!> (Sl:string, S2:string): extra-boolean expr 


Lexicographic comparison of strings. 


String!<!= (Sl:string, S2:string): extra-boolean expr 


Lexicographic comparison of strings. 


String!>!= (Sl:string, S2:string): extra-boolean expr 


Lexicographic comparison of strings. 


String!<!> (Sl:string, S2:string): extra-boolean expr 


Lexicographic comparison of strings. 


String!-LessP (Si:string, S2:string): extra-boolean expr 
Lexicographic comparison of strings. Case differences are 
ignored. 

String!-GreaterP (Si:string, S2:string): extra-boolean expr 
Lexicographic comparison of strings. Case differences are 
ignored. 

String!-Not!-GreaterP (Sl:string, S2:string): extra-boolean expr 
Lexicographic comparison of strings. Case differences are 
ignored. 

String!-Not!-LessP (Si:string, S2:string): extra-boolean expr 
Lexicographic comparison of strings. Case differences are 


ignored. 
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String!-Not!-Equal (Si:string, S2:string): extra-boolean expr 
Lexicographic comparison of strings. Case differences are 
ignored. 

Make!-String (I:integer, C:character): string expr 
Construct a string of length I filled with character C. C is 
optional. 

String!-Repeat (S:string, I:integer): string expr 


Appends copy of S to itself total of I-1 times. 


String!-Trim (BAG:{list, string}, S:string): string expr 


Remove leading and trailing characters in BAG from a string S. 


String!-Left!-Trim (BAG: {list, string}, S:string): string expr 


Remove leading characters from string. 


String!-Right!-Trim (BAG:{list, string}, S:string): string expr 


Remove trailing characters from string. 


String!-UpCase (S:string): string expr 


Copy and raise all alphabetic characters in string. 


NString!-UpCase (S:string): string expr 


Destructively raise all alphabetic characters in string. 


String!-DownCase (S:string): string expr 


Copy and lower all alphabetic characters in string. 


NString!-DownCase (S:string): string expr 


Destructively raise all alphabetic characters in string. 
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String!-Capitalize (S:string): string expr 
Copy and raise first letter of all words in string; other letters 
in lower case. 

NString!-Capitalize (S:string): string -expr 
Destructively raise first letter of all words; other letters in 
lower case. 

String!-tol-List (S:string): list expr 


Unpack string characters into a list. 


String!-to!-Vector (S:string): vector expr 


Unpack string characters into a vector. 


SubString (S:string, Ci:character, C2:character): string expr 


Subsequence restricted to strings. C2 is optional. 


String!-Length (S:string): integer expr 


Last index of a string, plus one. 
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CHAPTER 9 
FLOW OF CONTROL 


9.1. Conditionals 9 
9.1.1. The Case Statement 9 
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9.4. Non-Local Exits 


Most of the constructs presented in this Chapter have a special syntax in 
RLISP. This syntax is presented along with the definitions of the 
underlying functions. Most of the examples are presented using RLISP 
syntax. 


\ 


9.1. Conditionals 


Cond ([U:form-1list]): any open-compiled, fexpr 


The LISP function Cond corresponds to the If statement of most 
programming languages. In RLISP this is simply the familiar If 
ee. Then ... Else construct. For example: 


IF predicate THEN action1 
ELSE action2 
==> (COND (predicate action1) 
(T action2)) 


Action? is evaluated if the predicate has a non-NIL evaluation; 
otherwise, action2 is evaluated. Dangling Elses are resolved in 
the ALGOL manner by pairing them with the nearest preceding Then. 
For example: 


IF F(X) THEN 
IF G(Y) THEN PRINT(X) 
ELSE PRINT(Y); 


is equivalent to 
IF F(X) THEN 
<< IF G(Y) THEN PRINT(X) 
i ELSE PRINT(Y) >>; 


Note that if F(X) is NIL, nothing is printed. 
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Taken simply as a function, without RLISP syntax, the arguments 
to Cond have the form: 


(COND (predicate action action ...) 
(predicate action action ...) 


(predicate action action +...) ) 


The predicates are evaluated in the order of their appearance 
until a non-NIL value is encountered. The corresponding actions 
are evaluated and the value of the last becomes the value of the 
Cond. The dangling Else example above is: 


(COND ((F X) (COND ((G X) (PRINT X)) 
( T (PRINT Y)) ) )) 


The actions may also contain the special functions Go, Return», 
Exit, and Next, subject to the constraints on placement of these 
functions given in Section 9.2. In these cases, Cond does not 
have a defined value, but rather an effect. If no predicate is 
non-NIL, the value of Cond is NIL. 


following MACROs are defined in the USEFUL module for convenience, 


mostly used from LISP syntax: 


If (): any macro 


If is a macro to simplify the writing of a common form of Cond in 
which there are only two clauses and the antecedent of the second 
is T. It cannot be used in RLISP syntax. 


(IF <TEST> <THEN-CLAUSE> <ELSE1>...<ELSEn>) 
The <THEN-CLAUSE> is evaluated if and only if the test is 


non-NIL, otherwise the ELSES are evaluated, and the last 
returned. There may be zero ELSEs. 


Related macros for common COND forms are WHEN and UNLESS. 


When (): any | macro 


(WHEN <TEST> S1 S2 ... Sn) 


evaluates the Si and returns the value of Sn if and only if 
<TEST> is non=-NIL. Otherwise When returns NIL. 


cu) 


uJ 
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Unless (): any macro 


(UNLESS <TEST> S1 S2 ... Sn) 
<=> (WHEN (NOT <TEST>) S1 S2 ... Sn) 


While And and Or are primarily of interest as Boolean connectives, they 
are often used in LISP as conditionals. For example, 


(AND (FOO) (BAR) (BAZ)) 
has the same result as 
(COND ((FOO) (COND ((BAR) (BAZ))))) 


See Section 4.2.3. 


9.1.1. The Case Statement 

PSL provides a numeric case statement, that is compiled quite 
efficiently; some effort is made to examine special cases (compact vs. non 
compact sets of cases, short vs. long sets of cases, etc.). It has mostly 
been used in SYSLISP mode, but can also be used from LISP mode provided 
that case-tags are numeric. There is also an FEXPR, CASE, for the 
interpreter. 


The RLISP syntax is: 


Case-Statement ::= CASE expr OF case-list END 


Case-list ::= Case-expr [; Case-list ] 

Case-expr ::= Tag-expr : expr 

tag-expr 33= DEFAULT | OTHERWISE | 
tag | tag, tag ... tag | 
tag TO tag 

Tag s:= Integer | Wconst-Integer 


For example: 


CASE i OF 
1: Print("First"); 
2533 Print("Second") ; 


4 to 10: Print("Third") ; 
Default: Print("Fourth"); 
END 
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The RLISP syntax parses into the following LISP form: 


Case (I:form,[U:case-list]): any open-compiled, fexpr 


— ee — ee m 


I is meant to evaluate to an integer, and is used as a selector 


amongst the various Us. Each case-list has the form: 


NIL -> default case 
(11 12 ... In) -> where each Ik is an integer or 
(RANGE low high) 


The above example becomes: 


(CASE i ((1) (Print "First")) 
((2 3) (Print "Second" )) 
(((Range 4 10)) (Print "Third")) 

( NIL (Print "Fourth"))) 


[??? Perhaps we should move SELECTQ (and define a SELECT) from the 
COMMON module to the basic system 22??] 


9.2. Sequencing Evaluation 


These functions provide for explicit control sequencing, and the 
definition of blocks altering the scope of local variables. 


ProgN ([U:form]): any open-compiled, fexpr 
U is a set of expressions which are executed sequentially. The 


value returned is the value of the last expression. 


Prog2 (A:form, B:form): any open-compiled, expr 
Returns the value of B (the second argument). 


[??? Redefine prog2 to take N arguments, return second. ???] 


Prog1 ([U:form]): any macro 


Progl is a function defined in the USEFUL package; to use it, 
type LOAD USEFUL;. Progi evaluates its arguments in order, like 
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ProgN, but returns the value of the first. 


Prog (VARS:id-list, [PROGRAM:{id, form}]): any open-compiled, fexpr 


VARS is a list of ids which are considered FLUID if the Prog is 
interpreted and LOCAL if compiled (see the "Variables and 


Bindings" Section, 10.2). The Prog's variables are allocated 
space if the Prog form is applied, and are deallocated if the 
Prog is exited. Prog variables are initialized to NIL. The 


PROGRAM is a set of expressions to be evaluated in order of their 
appearance in the Prog function. identifiers appearing in the 
top level of the PROGRAM are labels which can be referred to by 
Go. The value returned by the Prog function is determined by a 
Return function or NIL if the Prog "falls through". 


There are restrictions as to where a number of control functions, such as 
Go and Return, may be placed. This is so that they may have only locally 
determinable effects. Unlike most LISPs, which make this restriction only 
in compiled code, PSL enforces this restriction uniformly in both compiled 
and interpreted code. Not only does this help keep the semantics of 
compiled and interpreted code the same, but we believe it leads to more 
readable programs. For cases in which a non-local exit is truly required, 
there are the functions Catch and Throw, described in Section 9.4. 


The functions so restricted are Go, Return, Exit, and Next. They must be 
placed at top-level within the surrounding control structure to which they 
refer (e.g. the Prog which Return causes to be terminated), or nested 
within only selected functions. The functions in which they may be nested 
(to arbitrary depth) are: 

- ProgN (compound statement) 
- actions of Conds (if then else) 


Go (LABEL:id): None Returned open-compiled, fexpr 


Go alters the normal flow of control within a Prog function. The 
next statement of a Prog function to be evaluated is immediately 


preceded by LABEL. A Go may appear only in the following 
situations: 


a. At the top level of a Prog referring to a LABEL that also 
appears at the top level of the same Prog. 
be As the action of a Cond item 


i. appearing on the top level of a Prog. 
ii. which appears as the action of a Cond item to any 
level. 
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Cc. As the last statement of a ProgN 


i. which appears at the top level of a Prog or ina 
ProgN appearing in the action of a Cond to any level 
subject to the restrictions of b.i, or b.ii. 

ii. within a ProgN or as the action of a Cond in a ProgN 
to any level subject to the restrictions of b.i, 
b.ii, and’ c.i. 


If LABEL does not appear at the top level of the Prog in which 
the Go appears, an error occurs: 


+ LABEL is not a label within the current scope 


If the Go has been placed in a position not defined by rules a-c, 
another error is detected: 


*##*%%% Illegal use of GO To LABEL 


Return (U:form): None Returned open-compiled, expr 


Within a Prog, Return terminates the evaluation of a Prog and 
returns U as the value of the Prog. The restrictions on the 
placement of Return are exactly those of Go. Improper placement 
of Return results in the error: 


###42% Tllegal use of RETURN 


9.3. Iteration 


While (E:form, [S:form]): NIL macro 


In RLISP syntax this is While ... DO ... » Note that in RLISP 
syntax there may be only a single expression after the Do; 
however, it may be a ProgN delimited by <<...>>. This is the 
most commonly used construct for indefinite iteration in LISP. E 
is evaluated; if non-NIL, the elements of S are evaluated from 
left to right and then the process is repeated. If E evaluates 
to NIL the While returns NIL. Exit may be used to terminate the 
While from within the body and to return a value. Next may be 
used to terminate the current iteration. 
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Repeat (E:form, [S:form]): NIL macro 


Next 


Exit 


The S's are evaluated left to right, and then E is evaluated. 
This is repeated until the value of E is NIL, if Repeat returns 
NIL. Next and Exit may be used in the S's branch to the next 
iteration of a Repeat or to terminate one and possibly return a 
value. Go, and Return may appear in the S's. The RLISP syntax 
for Repeat is Repeat Until. Like While, RLISP syntax only allows 
a Single S, so 


REPEAT E S1 S2 
Should be written in RLISP as 
REPEAT << S13 S2 >> UNTIL E 


[??? maybe do REPEAT S1 ... Sn E 277] 


(): None Returned open-compiled, restricted, macro 


With no argument, this terminates the current iteration of the 
most closely surrounding While, Repeat, or Loop, and causes the 
next to commence. See the note in Section 9.2 about the lexical 
restrictions on placement of this construct, which is essentially 
a GO. 


(LU:form]): None Returned 


The U's are evaluated left to right, the most closely surrounding 
While, Repeat, or Loop is terminated, and the value of the last U 
is returned. With no arguments, NIL is returned. See the note 
in Section 9.2 about the lexical restrictions on placement of 
this construct, which is essentially a Return. 


open-compiled,restricted, macro 


While and Repeat each macro expand into a Prog; Next and Exit are macro 


expanded into a Go and a Return respectively to this Prog. 


Thus using a 


Next or an Exit within a Prog within a While or Repeat will result only in 
an exit of the internal Prog. In RLISP use 


WHILE E DO << Slj+...¿EXIT(1)3...38n>> 


not 


WHILE E DO BEGIN S1;...;EXIT(1);...3Sn;END; 
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9.3.1. For 

The For construct has been partially implemented in the resident PSL; a 
more satisfactory version is described below and can be loaded on the 
Dec-20 by loading USEFUL. 


For ([S:form]): any macro 


The arguments to For are clauses; each clause is itself a list of 
a keyword and one or more arguments. The clauses may introduce 
local variables, specify return values and when the iteration 
should cease, have side-effects, and so on. Before going 
further, it is probably best to give an example. The following 
function zips together three lists into a list of three element 
lists. 


(DE ZIP3 (X Y 2) 
(FOR (IN U X) (IN V Y) (IN W Z) (COLLECT (LIST U V W)))) 


The three In clauses specify that their first argument should 
take successive elements of the respective lists, and the Collect 
Clause specifies that the answer should be a list built out of 
its argument. For example, 


(zip3 '(1 23 4) "(a bed) "(wx y z)) 


is 


((1 a w)(2 b x)(3 c y)(4 d 2)) 


All the possible clauses are described below. The first few 
introduce iteration variables. Most of these also give some 
means of indicating when iteration should cease. For example, if 
a list being mapped over by an In clause is exhausted, iteration 
must cease. If several such clauses are given in For expression, 
iteration ceases when one of the clauses indicates it should, 
whether or not the other clauses indicate that it should cease. 


(IN Vi V2) 
assigns the variable V1 successive elements of the list 


Ve. 


This may take an additional, optional argument: a 
function to be applied to the extracted element or 
sublist before it is assigned to the variable. The 
following returns the sum of the lengths of all the 
elements of L. 


L 


L 


J 


J 


J 


J 
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[??? Rather a kludge -- not sure why this is here. 
Perhaps it should come out again. ???] 


(DE SUMLENGTHS (L) 
(FOR (IN N L LENGTH) (SUM N))) 


For example, (SumLengths '((1 2 3 4 5)(a b e)(x y))) is 
10. 


assigns the variable V1 successive Cdrs of the list V2. 


(FROM VAR INIT FINAL STEP) 


is a numeric clause. The variable is first assigned 
INIT, and then incremented by step until it is larger 
than FINAL. INIT, FINAL, and STEP are optional. INIT 
and STEP both default to 1, and if FINAL is omitted the 
iteration continues until stopped by some other means. 
To specify a STEP with INIT or FINAL omitted, or a 
FINAL with INIT omitted, place NIL (the constant -- it 
cannot be an expression) in the appropriate slot to be 
omitted. FINAL and STEP are only evaluated once. 


e 


(FOR VAR INIT NEXT) 


assigns the variable INIT first, and subsequently the 
value of the expression NEXT. INIT and NEXT may be 
omitted. Note that this is identical to the behavior 
of iterators in a Do. 


(WITH V1 V2 ... Vn) 


introduces N locals, initialized to NIL. In addition, 
each Vi may also be of the form (VAR INIT), in which 
case it is initialized to INIT. 


(DO S1 S2 ... Sn) 


causes the Si's to be evaluated at each iteration. 


There are two clauses which allow arbitrary code to be executed 
before the first iteration, and after the last. 


(INITIALLY S1 S2 ... Sn) 


causes the Si's to be evaluated in the new environment 
(i.e. with the iteration variables bound to their 
initial values) before the first iteration. 
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(FINALLY S1 S2 ... Sn) 
causes the Si's to be evaluated just before the 
function returns. 


The next few clauses build up return types. Except for the 
RETURNS/RETURNING clause, they may each take an additional 
argument which specifies that instead of returning the 
appropriate value, it is accumulated in the specified variable. 
For example, an unzipper might be defined as 


(DE UNZIP3 (L) 

(FOR (U IN L) (WITH X Y 2) 
(COLLECT (CAR U) X) 
(COLLECT (CADR U) Y) 
(COLLECT (CADDR U) Z) 
(RETURNS (LIST X Y Z)))) 


This is essentially the opposite of Zip3. Given a list of three 
element lists, it unzips them into three lists, and returns a 
list of those three lists. For example, (unzip '((1 a w)(2 b 
x)(3 e y)(4 d 2))) is ((1 2 3 4)(a be d)(w x y z)). 


(RETURNS EXP) 
causes the given expression to be the value of the For. 
Returning is synonymous with returns. It may be given 
additional arguments, in which case they are evaluated 
in order and the value of the last is returned 
(implicit ProgN). 


(COLLECT EXP) 
causes the successive values of the expression to be 
collected into alist. Each value is Appended to the 
end of the list. 


(UNION EXP) 
is similar, but only adds an element to the list if it 
is not equal to anything already there. 


(CONC EXP) 
causes the successive values to be NConc'd together. 


(JOIN EXP) 
causes them to be appended. 


L 


J 


J 
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(COUNT EXP) 


returns the number of times EXP was non-NIL. 


(SUM EXP), (PRODUCT EXP), (MAXIMIZE EXP), and (MINIMIZE EXP) 
do the obvious. Synonyms are summing, maximizing, and 
minimizing. 


( ALWAYS EXP) 
returns T if EXP is non-NIL on each iteration. If EXP 
is ever NIL, the loop terminates immediately, no 
epilogue code, such as that introduced by finally is 
run, and NIL is returned. 


(NEVER EXP) 
is equivalent to (ALWAYS (NOT EXP)). 


(WHILE EXP) and (UNTIL EXP) 

Explicit tests for the end of the loop may be given 
using (WHILE EXP). The loop terminates if EXP becomes 
NIL at the beginning of an iteration. (UNTIL EXP) is 
equivalent to (WHILE (NOT EXP)). Both While and Until 
may be given additional arguments; (WHILE El E2 +... En) 
is equivalent to (WHILE (AND El E2 +... En)) and 
(UNTIL El E2 +... En) is equivalent to 
(UNTIL (OR El E2 +... En)). 


(WHEN EXP) 
causes a jump to the next iteration if EXP is NIL. 


(UNLESS EXP) 
is equivalent to (WHEN (NOT EXP)). 


For is a general iteration construct similar in many ways to the LISP 
Machine and MACLISP Loop construct, and the earlier Interlisp CLISP 
iteration construct. For, however, is considerably simpler, far more 
"lispy", and somewhat less powerful. For only works in LISP syntax. 


All variable binding/updating still precedes any tests or other code. 
Also note that all When or Unless clauses apply to all action clauses, not 
just subsequent ones. This fixed order of evaluation makes For less 
powerful than Loop, but also keeps it considerably simpler. The basic 
order of evaluation is 
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a+. bind variables to initial values (computed in the outer 
environment) 


b. execute prologue (i.e. Initially clauses) 


C. while none of the termination conditions are satisfied: 


i. check conditionalization clauses (When and Unless), and 
start next iteration if all are not satisfied. 


ii. perform body, collecting into variables as necessary 


iii. next iteration 


d. (after a termination condition is satisfied) execute the 
epilogue (i.e. Finally clauses) 


For does all variable binding/updating in parallel. There is a similar 
macro, For*, which does it sequentially. 


For!* ([S:form]): any macro 


9.3.2. Mapping Functions 

The mapping functions long familiar to LISP programmers are present in 
PSL. However, we believe that the For construct described above is 
generally more useful, Since it obviates the usual necessity of 
constructing a lambda expression, and is often more transparent. Mapping 
functions with more than two arguments are not currently supported. Note 
however that several lists may be iterated along with For, and with 
considerably more generality. For example: 


BEGIN SCALAR I; 
I := 0; 
RETURN MAPCAR(L, FUNCTION LAMBDA X; <<I:=I+1; I . X >>) 
END; 
may be expressed more transparently as 


FOR X IN L AS I FROM 1 COLLECT I . ELEM; 


Note that the RLISP syntax is not yet implemented. 


ForEach (Usany): any macro 


Although in LISP syntax one must use the form ForEach, in RLISP 
syntax one may use either ForEach or For Each. This macro is 


J 


J 
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used by the map functions as follows: 


Possible forms are: 

U DO (FOO X)) --> (MAPC U (FUNCTION 
(LAMBDA (X) (FOO X)))) 

U COLLECT (FOO X))--> (MAPCAR U ...) 

U CONC (FOO X)) -=> (MAPCAN U +...) 

U DO (FOO X)) ==> (MAP U +...) 

U COLLECT (FOO U))-=> (MAPLIST U ...) 

U CONC (FOO X)) ==> (MAPCON U ...) 


(FOREACH X IN 


(FOREACH X IN 
(FOREACH X IN 
(FOREACH X ON 
(FOREACH X ON 
(FOREACH X ON 


Map (X:list, FN:function): NIL 


Applies FN to 


This is equivalent to: 


FOR EACH U 


ON X DO FN(U); 


MapC (X:list, FN:function): NIL 


FN is applied to successive Car segments 


returned. This is equivalent to: 


FOR EACH U 


MapCan (X:list, FN: 


A concatenated list of FN applied to 


is returned. 


FOR EACH U 


MapCar (X:list, FN: 


Returned is a constructed list, 


IN X DO FN(U); 


funetion): list 


This is equivalent to: 


IN X CONC FN(U); 


function): list 


successive Cdr segments of X. 


Flow Of Control 
page 9.13 


of list X. NIL is 


applied to each Car of list X. This is equivalent to: 


FOR EACH U 


MapCon (X:list, FN: 


IN X COLLECT FN(U); 


function): list 


Returned is a concatenated list of FN applied to successive 


segments of X. 


This is equivalent to: 


NIL is returned. 


successive Car elements of X 


the elements of which are FN 


Cdr 


expr 


expr 


expr 
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FOR EACH U ON X CONC FN(U); 


MapList (X:list, FN:function): list expr 


Returns a constructed list, the elements of which are FN applied 
to successive Cdr segments of X. This is equivalent to: 


FOR EACH U ON X COLLECT FN(U); 


9.3.3. Do - 

Do and Let are now partially implemented in a package called USEFUL. To 
find out more about this package type HELP USEFUL; in RLISP. To use the 
package type in LOAD USEFUL;. 


Do (A:list, B:list, [S:form]): any macro - 


The Do macro is a general iteration construct similar to that of 
LISPM and friends. However, it does differ in some details; in 
particular it is not compatible with the "old style Do" of 
MACLISP, nor does it support the "no end test means once only" 
convention. Do has the form 


(DO (11 12 ... In) 
(TEST R1 R2 ... Rk) 
S1 
s2 


Sm) 


in which there may be zero or more I's, Rts, and S's. In general 
the I's have the form 


(var init step) 


On entry to the Do form, all the inits are evaluated, then the 
variables are bound to their respective inits. The test is 
evaluated, and if non-NIL the form evaluates the R's and returns 
the value of the last one. If none are supplied it returns NIL. 
If the test evaluates to NIL the S's are evaluated, the variables 
are assigned the values of their respective steps in parallel, 
and the test evaluated again. This iteration continues until 
test evaluates to a non-NIL value. Note that the inits are 
evaluated in the surrounding environment, while the steps are 
evaluated in the new environment. The body of the Do (the S's) 
is a Prog, and may contain labels and Go's, though use of this is 
discouraged. It may be changed at a later date. Return used 
within a Do returns immediately without evaluating the test or 
exit forms (R's). 
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There are alternative forms for the I's: If the step is omitted, 
the variable's value is left unchanged. If both the init and 
step are omitted or if the I is an id, it is initialized to NIL 
and left unchanged. This is particularly useful for introducing 
dummy variables which are SetQ'd inside the body. 


Do!® (A:list, B:list, [C:form]): any macro 
Do!* is like Do, except the variable bindings and updatings are 


done sequentially instead of in parallel. 


Do-Loop (A:list, B:list, C:list, [S:form]): any macro 


Do=Loop is like Do, except that it takes an additional argument, 
a prologue. The general form is 


(DO-LOOP (11 12 ... In) 
(P1 P2 ... Pj) 
(TEST R1 R2 ... Rk) 
S1 
s2 


Sm) 


This is executed just like the corresponding Do, except that 
after the bindings are established and initial values assigned, 
but before the test is first executed the P's are evaluated, in 
order. Note that the P's are all evaluated exactly once 
(assuming that none of the P's err out, or otherwise throw to a 
surrounding context). 


Do-Loop!* (A:list, Bslist, Cslist, [S:form]): any macro 


Do-Loop!* does the variable bindings and undates sequentially 
instead of in parallel. 

Let (A:list, [B:form]): any macro 
Let is a macro giving a more perspicuous form for writing lambda 
expressions. The basic form is 


(LET ((V1 11) (v2 12) ...(Vn In)) S1 S2 ... Sn) 


The I's are evaluated (in an unspecified order), and then the V's 
are bound to these values, the S's evaluated, and the value of 
the last is returned. Note that the I's are evaluated in the 
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outer environment before the V's are bound. 


Let! (A:list, [B:form]): any macro 


Let!# is just like Let except that it makes the assignments 
sequentially. That is, the first binding is made before the 
value for the second one is computed. 


9.4. Non=-Local Exits 


[ Notes: Catch and Throw will probably be reimplemented shortly so that 
they only evaluate their second args once, not twice. ] 


One occasionally wishes to discontinue a computation in which the lexical 
restrictions on placement of Return are too restrictive. The non-local 
exit constructs Catch and Throw exist for these cases. They should not, 
however, be used indiscriminately. The lexical restrictions on their more 
local counterparts ensure that the flow of control can be ascertained by 
looking at a single piece of code. With Catch and Throw, control may be 
passed to and from totally unrelated pieces of code. Under some 
conditions, these functions are invaluable. Under others, they can wreak 
havoc. 


Catch (TAG:id, FORM:form): fany, None Returned} expr 


Catch calls Eval on FORM. If during this evaluation 
Throw(TAG,VAL) occurs, Catch immediately returns VAL. If no 
Throw occurs, the value of FORM is returned. Note that in 
general only Throws with the same TAG are caught. Throws whose 
TAG is not Eq to that of Catch are passed on out to surrounding 
Catches. A TAG of NIL, however, is special. Catch(NIL, FORM) 
catches any Throw. 


The FLUID variables THROWSIGNAL!* and THROWTAG!* may be 
interrogated to find out if the most recently evaluated Catch was 
Thrown to, and what tag was passed to the Throw. THROWSIGNAL! * 
is Set to NIL upon normal exit from a Catch, and to T upon normal 
exit from Throw. THROWTAG!* is Set to the first argument passed 
a Throw. (Mark a place to Throw to, Eval FORM.) 


Throw (TAG:id, VAL:any): None Returned expr 
This passes control to the closest surrounding Catch with an Eq 
or null TAG. If there is no such surrounding Catch it is an 
error in the context of the Throw. That is, control is not 


SN ERE 0 EEE = Een 


Thrown to the top level before the call on Error. (Non-local 
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Goto.) 


Note that Error and ErrorSet are implemented by means of Catch and Throw, 
using a tag of !$ERROR!$ (see Chapter 15). 


-J 
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CHAPTER 10 
FUNCTION DEFINITION AND BINDING 


10.1. Function Definition in PSL 10.1 
10.1.1. Notes on Code Pointers 10.1 
10.1.2. Functions Useful in Function Definition 10.2 
10.1.3. Short Calls on PutD for LISP Syntax Users 10.4 
10.1.4. Function Definition in RLISP Syntax 10.5 
10.1.5. Low Level Function Definition Primitives 10.5 

: 10.1.6. Function Type Predicates 10.6 

10.2. Variables and Bindings 10.6 
10.2.1. Binding Type Declaration 10.7 
10.2.2. Binding Type Predicates 10.8 

10.3. User Binding Functions 10.8 
10.3.1. Funargs, Closures and Environments 10.9 


10.1. Function Definition in PSL 


Functions in PSL are GLOBAL entities. To avoid function-variable naming 
clashes, the Standard LISP Report required that no variable have the same 


name as a function. There is no conflict in PSL, as separate function 
cells and value cells are used. A warning message is given for 
compatibility. The first major Section in this Chapter describes how to 


define new functions; the second describes the binding of variables in PSL. 
The final Section presents binding functions useful in building new 
interpreter functions. 


10.1.1. Notes on Code Pointers 

A code-pointer may be displayed by the Print functions or expanded by 
Explode. The value appears in the convention of the implementation 
(#<Code:nnn> on the DEC-20 and VAX). A code-pointer may not be created by 
Compress. (See Chapter 13 for descriptions of Explode and Compress.) The 
code-pointer associated with a compiled function may be retrieved by GetD 
and is valid as long as PSL is in execution (on the DEC-20 and VAX, 
compiled code is not relocated, so code-pointers do not change). A 
code-pointer may be stored using PutD, Put, SetQ and the like or by being 
bound to a variable. It may be checked for equivalence by Eq. The value 
may be checked for being a code-pointer by the CodeP function. 
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10.1.2. Functions Useful in Function Definition 

In PSL, ids have a function cell that usually contains an executable 
instruction which either JUMPs directly to the entry point of a compiled 
function or executes a CALL to an auxiliary routine that handles 
interpreted functions, undefined functions, or other special services (such 
aS auto-loading functions, etc). The user can pass anonymous function 
objects around either as a code-pointer, which is a tagged object referring 
to a compiled code block, or a lambda expression, representing an 
interpreted function. 


PutD (FNAME:id, TYPE:ftype, BODY:{lambda, code-pointer}): id expr 


Creates a function with name FNAME and type TYPE, with BODY as 
the function definition. If successful, PutD returns the name of 
the defined function. If the function is a code-pointer or is 
compiled (i.e. !*COMP=T as the function was defined), a special 
instruction to jump to the start of the code is placed in the 
function cell. If it is interpreted, the lambda expression is 
Saved on the property list and a call to an interpreter function 
(LambdaLink) is placed in the function cell. The TYPE is 
recorded on the property list of FNAME if it is not an expr. 


[??? Should we check arglist 0<=15 for exprs or =1 for 
fexprs, macros and nexprs. Should we expand macros. ???] 


After using PutD, GetD returns a pair with the function's TYPE 
and definition. Likewise, the GlobalP predicate returns T if 
queried with the function name. 


If the function FNAME has already been declared as a GLOBAL or 
FLUID variable the warning: 


*#*#% FNAME is a non-local variable 


occurs, but the function is defined. If function FNAME already 
exists, a warning mesSage appears: 


*** Function FNAME has been redefined 


Note: All function types may be compiled. 


The following flags are useful when defining functions. 


!*REDEFMSG (Initially: T) flag 


If !*REDEFMSG is not NIL, the message 
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*** Function *FOO' has been redefined 
is printed whenever a function is redefined. 
IMUSERMODE (Initially: T) flag 


Controls action on redefinition of a function. All functions 
defined if !*USERMODE is T are flagged USER. Functions which are 
flagged USER can be redefined freely. If an attempt is made to 
redefine a function which is not flagged USER, the query 


Do you really want to redefine the system function *FOO'? 


is made, requiring a Y, N, YES, NO, or B response. B starts the 
break loop, so that one can change the setting of !*USERMODE. 
After exiting the break loop, one must answer Y, Yes, N, or No. 
See YesP in Chapter 14. If !*UserMode is NIL, all functions can 
be redefined freely, and all functions defined have the USER flag 
removed. This provides some protection from redefining system 
functions. 


COMP (Initially: NIL) 


GetD 


The value of !*COMP controls whether or not PutD compiles the 
function defined in its arguments before defining it. If !*COMP 
is NIL the function is defined as a lambda expression. If !*COMP 
is non-NIL, the function is first compiled. Compilation produces 
certain changes in the semantics of functions, particularly FLUID 
type access. 


(Usany): {NIL, pair} 


If U is not the name of a defined function, NIL is returned. If 


U is a defined function then the pair 
({expr, fexpr, macro, nexpr} . {code-pointer, lambda}) is 
returned. 


CopyD (NEW:id, OLD:id): NEW:id 


The function body and type for NEW become the same as OLD. If no 
definition exists for OLD an error: 


#***% OLD has no definition in COPYD 


is given. NEW is returned. 


flag 


expr 


expr 
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RemD (U:id): {NIL, pair} expr 


Removes the function named U from the set of defined functions. 
Returns the (ftype . function) pair or NIL, as does GetD. The 
GLOBAL/function attribute of U is removed and the name may be 
used subsequently as a variable. 


10.1.3. Short Calls on PutD for LISP Syntax Users 

The functions De, Df, Dn, Dm, and Ds are most commonly used in the LISP 
syntax form of PSL. They are difficult to use from RLISP as there is not a 
convenient way to represent the argument list. The functions are compiled 
if !*COMP is T. 


[??? Add a macro or parsing function Args to make it possible to use 
these in RLISP [why bother] ???] 
De (FNAME:id, PARAMS:id-list, [FN:form]): id macro 


The forms FN are made into a lambda expression with the formal 
parameter list PARAMS, and are added to the set of defined 


functions with the name FNAME. Previous definitions of the 
function are lost. The function created is of type expr. The 


name of the defined function is returned. 


Df (FNAME:id, PARAM: ac -list, FN:any): id macro 
The function FN with formal parameter PARAM is added to the set 
of defined functions with the name FNAME. Any previous 
definitions of the function are lost. The function created is of 
type fexpr. The name of the defined function is returned. 


Dn (FNAME:id, PARAM:id-list, FN:any): id macro 
The function FN with formal parameter PARAM is added to the set 
of defined functions with the name FNAME. Any previous 


definitions of the function are lost. The function created is of 
type nexpr. The name of the defined function is returned. 


Dm (MNAME:id, PARAM:id-list, FN:any): id | | macro 
The macro FN with the formal parameter: PARAM is added to the set 
of defined functions with the name  MNAME, Any previous 
definitions of the function are overwritten. The function 


created is of type macro. The name of the macro is returned. 


PSL Manual 22 July 1982 Function Definition 
section 10.1 page 10.5 
Ds (SNAME:id, PARAM:id-list, FN:any): id macro 


Defines the smacro SNAME. 
[??? Explain as a macro generator-- see pu:define-smacro.red. 


227] 


10.1.4. Function Definition in RLISP Syntax 
In RLISP mode, procedures are defined by using the Procedure construct, 
as discussed in Chapter 3. 


type PROCEDURE name(args); 
body; 


10.1.5. Low Level Function Definition Primitives 
The following functions are used especially by PutD and GetD, defined 
above in Section 10.1.2, and by Eval and Apply, defined in Chapter 11. 


FUnBoundP (U:id): boolean expr 
Tests whether there is a definition in the function cell of U; 
returns T if so, NIL if not. 

FLambdaLinkP (U:id): boolean i expr 


Tests whether U is an interpreted function; return T if so, NIL 
if not. 


FCodeP (U:id): boolean expr 
Tests whether U is a compiled function; returns T if so, NIL if 
not. 

MakeFUnBound (U:id): NIL , expr 


Makes U an undefined function by planting a special call to an 
error function in the function cell of U. 


MakeFLambdaLink (U:id): NIL expr 


[??? definition ???] 


Function Definition ` 22 July 1982 PSL Manual 


page 10.6 section 10.1 
MakeFCode (U:id, C:code-pointer): NIL expr 


[?2? definition ???] 


GetFCodePointer (U:id): code-pointer . expr 
Gets the code-pointer for U. 

10.1.6. Function Type Predicates 

See Section 2.7 for a discussion of the function types available in PSL. 

ExprP (U:any): boolean expr 
Test if U is a code-pointer, lambda form, or an id with expr 
definition. 

FExprP (U:any): boolean expr 


Test if U is an id with fexpr definition. 


NExprP (U:any): boolean © expr 


Test if U is an id with nexpr definition. 


MacroP (U:any): boolean expr 


Test if U is an id with macro definition. 


10.2. Variables and Bindings 


Variables in PSL are ids, and associated values are usually stored in and 
retrieved from the value cell of this id. If variables appear as 
parameters in lambda expressions or in Prog's, the contents of the value 
cell are saved on a binding stack. A new value or NIL is stored in the 
value cell and the computation proceeds. On exit from the lambda or Prog 
the old value is restored. This is called the "shallow binding" model of 
LISP. It is chosen to permit compiled code to do binding efficiently. For 
even more efficiency, compiled code may eliminate the variable names and 
simply keep values in registers or a stack. The scope of a variable is the 
range over which the variable has a defined value. There are three 
different binding mechanisms in PSL, 


LOCAL BINDING Only compiled functions bind variables locally. Local 


J 


oo 


J 


~~ 
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variables occur as formal parameters in lambda expressions 
and as LOCAL variables in Prog's. The binding occurs as a 
lambda expression is evaluated or as a Prog form is 
executed. The scope of a local variable is the body of the 
function in which it is defined. 


FLUID BINDING FLUID variables are GLOBAL in scope but may occur as formal 


parameters or Prog form variables. In interpreted 
functions, all formal parameters and LOCAL variables are 
considered to have FLUID binding until changed to LOCAL 
binding by compilation. A variable can be treated as a 
FLUID only by declaration. If FLUID variables are used as 
parameters or LOCALs they are rebound in such a way that the 
previous binding may be restored. All references to FLUID 
variables are to the currently active binding. Access to 
the values is by name, going to the value cell. 


GLOBAL BINDING GLOBAL variables may never be rebound. Access is to the 


value bound to the variable. The scope of a GLOBAL variable 
is universal. Variables declared GLOBAL may not appear as 
parameters in lambda expressions or as Prog form variables. 
A variable must be declared GLOBAL prior to its use as a 
GLOBAL variable since the default type for undeclared 
variables is FLUID. Note that the interpreter does not stop 
one from rebinding a global variable. The compiler will 
issue a warning in this situation. 


10.2.1. Binding Type Declaration 
Fluid (IDLIST:id-list): NIL expr 
The ids in IDLIST are declared as FLUID type variables (ids not 


previously declared are initialized to NIL). Variables in IDLIST 
already declared FLUID are ignored. Changing a variable's type 

from GLOBAL to FLUID is not permissible and results in the error: 
¥**#**% TD cannot be changed to FLUID 

Global (IDLIST:id-list): NIL o | expr 

The ids of IDLIST are declared GLOBAL type variables. If an id 

has not been previously declared, it is initialized to NIL. 
Variables already declared GLOBAL are ignored. Changing a 
variable's type from FLUID to GLOBAL is not permissible and 
results in the error: 
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*x**** TD cannot be changed to GLOBAL 


UnFluid (IDLIST:id-list): NIL 


The variables in IDLIST which have been declared 
variables are no longer considered as FLUID variables. 


are ignored. This affects only compiled functions, as free 


variables in interpreted functions are automatically 
FLUID (see [Griss 81]). 


10.2.2. Binding Type Predicates 


FluidP (U:any): boolean 


If U is FLUID (by declaration only), T is returned; otherwise, 


NIL is returned. 


GlobalP (U:any): boolean 


If U has been declared GLOBAL or is the name of a defined 


function, T is returned; else NIL is returned. 


UnBoundP (U:id): boolean 


Tests whether U has no value. 


10.3. User Binding Functions 
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expr 


expr 


expr 


expr 


The following functions are available to build one's own interpreter 
functions that use the built-in FLUID binding mechanism, and interact well 
with the automatic unbinding that takes place during Throw and Error calls. 


[??? Are these correct when Environments are managed correctly ???] 


UnBindN (N:integer): Undefined 


Used in user-defined interpreter functions (like Prog) to restore 


previous bindings to the last N values bound. 


expr 


LJ 
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LBind1 (IDNAME:id, VALUETOBIND:any): Undefined expr 


Support for LAMBDA-like binding. The current value of IDNAME is 
saved on the binding stack; the value of VALUETOBIND is then 
bound to IDNAME. 


PBind1 (IDNAME:id): Undefined expr 


Support for Prog. Binds NIL to IDNAME after saving value on the 
binding stack. Essentially LBindT(CIDNAME, NIL) 


10.3.1. Funargs, Closures and Environments 
[??? Not yet connected to V3 ???] 


We currently have an experimental implementation of Baker's re-rooting 
funarg scheme [Baker 78], in which we always re-root upon binding; this 
permits efficient use of a GLOBAL value cell in the compiler. We are also 
considering implementing a restricted FUNARG or CLOSURE mechanism. 


This currently uses a module (ALTBIND) to redefine the fluid binding 
mechanism of PSL to be functionally equivalent to an a-list binding scheme. 
However, it retains the principal advantage of the usual shallow binding 
scheme: variable lookup is extremely cheap -- just look in a value cell. 
Typical LISP programs currently run about 8% slower if using ALTBIND than 
with the initial shallow binding mechanism. It is expected that this 8% 
difference will go away presently. This mechanism will also probably 
become a Standard part of PSL, rather than an add on module. 


To use ALTBIND simply do "load altbind;" ["(load altbind)" in LISP]. 
Existing code, both interpreted and compiled, should then commence using 
the new binding mechanism. 


The following functions are of most interest to the user: 


Closure (U:form): form . macro 


This is similar to Function, but returns a function closure 
including environment information, similar to Function in LISP 
1.5 and Function* in LISP 1.6 and MACLISP. Eval and Apply are 
redefined to handle closures correctly. Currently only closures 
of exprs are supported. 
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EvalInEnvironment (F:form, ENV:env-pointer): any expr 


ApplyInEnvironment (FN:function, ARGS:form-list, ENV:env-pointer): any expr 


These are like Eval and Apply, but take an extra, last argument, 
and environment pointer. They perform their work in this 
environment instead of the current one. 


The following functions should be used with care: 


CaptureEnvironment (): env-pointer expr 


Save the current bindings to be restored at some later point. 
This is best used inside a closure. CaptureEnvironment returns 
an environment pointer. This object is normally a circular list 
structure, and so should not be printed. The same warning 
applies to closures, which contain environment pointers. It is 
hoped that environment pointers will be made a new LISP data type 
soon, and will be made to print safely, relaxing this 
restriction. 


[??? add true envpointer ??7] 


RestoreEnvironment (PTR:env-pointer): Undefined expr 
Restore old bindings to what they were in the captured 
environment, PTR. 

ClearBindings (): Undefined expr 
Restore bindings to top level, i.e strip the entire stack. 


For a demonstration of closures, do (in RLISP) 
“in "PUsaltbind-tests.red";'. 


[??? Give a practical example ???] 


[ 


J 
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CHAPTER 11 
THE INTERPRETER 


11.1. Evaluator Functions Eval and Apply 11.1 
11.2. Support Functions for Eval and Apply 11.3 
11.3. Special Evaluator Functions, Quote, and Function 11.3 
11.4. Support Functions for Macro Evaluation 11.4 


11.1. Evaluator Functions Eval and Apply 


The PSL evaluator uses the function cell (SYMFNC(id#)) to access the 
address of some code to execute for each function, as described in Chapters 
10 and 22. This is either the entry address of a compiled function, or the 
address of a support routine that either signals undefined function or 
calls the lambda interpreter. The PSL model of a function call is to place 
the arguments (after treatment appropriate to function type) in 
"registers", and then JUMP or CALL the code in the function cell. 


Expressions which can be legally evaluated are called forms. They are 
restricted S-expressions: 


| constant 
| (id form ... form) % Normal function call 
| (special . any) % Special cases: COND, PROG, etc. 


$ usually fexprs or macros 


The definitions of Eval and Apply may clarify which expressions are forms. 


In Eval, Apply, and the support functions below, ContinuableError is used 
to indicate malformed lambda expressions, undefined functions or mismatched 
argument numbers; the user is permitted to correct the offending expression 
or to define a missing function inside a Break loop. Note Step in Section 
16.1.2, also. 


Eval (U:form): any expr 


The value of the form U is computed. The following is an 


approximation of the real code. 
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EXPR PROCEDURE EVAL(U); 
BEGIN SCALAR FN; 
IF IDP U THEN RETURN VALUECELL U; 
% ValueCell returns the contents of Value Cell 
% if ID is BoundP, else signals unbound error 
IF NOT PAIRP U THEN RETURN U; 
4 This is a "constant" which EVAL's to itself 
IF EQCAR(CAR U,'LAMBDA) THEN 
RETURN LAMBDAEVALAPPLY(CAR U, CDR U) 
IF CODEP CAR U THEN RETURN CODEEVALAPPLY(CAR U, CDR U); 
4% Lambda-expressions and code-pointers applied to 
% EVLIS'd argument list 
IF NOT IDP CAR U THEN RETURN 
CONTINU ABLEERROR(1101,"Il1-formed expression in EVAL",U); 
% permit user to correct U, and reevaluate. 
FN := GETD CAR U; 
IF NULL FN THEN RETURN 
CONTINU ABLEERROR(1001,"Undefined function EVAL",U); 
% user might define missing function and retry 
IF CAR FN EQ 'EXPR THEN 
RETURN 
IF CODEP CDR FN THEN CODEEVALAPPLY(CDR FN, CDR U) 
ELSE LAMBDAEVALAPPLY(CDR FN,CDR U); 
IF CAR FN EQ 'FEXPR THEN 
RETURN IDAPPLY1(CDR U,CAR U) 3; : 
IF CAR FN EQ 'MACRO THEN 
RETURN EVAL IDAPPLY1(U,CAR U) ; 
IF CAR FN EQ 'NEXPR THEN 
RETURN IDAPPLY1(EVLIS CDR U, CAR U) 3 
END; 
Apply (FN:{id,function}, ARGS:form-list): any expr 
Apply returns the value of FN with actual parameters ARGS. The 


actual parameters in ARGS are already in the form required for 
binding to the formal parameters of FN. We permit macros and 


fexprs to be applied; the effect is the same as Apply(Cdr 


GetD 


FN,ARGS); i.e. no fix-up is done to quote arguments, etc. as in 
some LISPs. A call to Apply using List on the second argument 
[e.g. Apply(F, List(X, Y))] is compiled so that the list is not 


actually constructed. 


The following is an approximation of the real code: 
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EXPR PROCEDURE APPLY(FN, ARGS); 
BEGIN SCALAR DEFN; 
Ir CODEP FN THEN RETURN CODEAPPLY(FN,ARGS); 
% Spread the ARGS into the registers and 
% transfer to the entry point of the function 
IF EQCAR(FN, 'LAMBDA) THEN RETURN LAMBDAAPPLY(FN, ARGS) ; 
% Bind the actual parameters in ARGS to the formal 
% parameters of the lambda expression. If the two 
% lists are not of equal length then signal 
% CONTINUABLEERROR( 1204, 
% “Number of parameters do not match", FN . ARGS); 
IF NOT IDP FN THEN RETURN 
CONTINU ABLEERROR( 1104, 
"Tll-formed Function in APPLY", FN . ARGS); 
IF NULL(DEFN := GETD FN) THEN RETURN 
CONTINU ABLEERROR( 1004, 
"Undefined function in Apply",FN . ARGS); 
RETURN APPLY(CDR DEFN, ARGS); 
> Do EXPR's, FEXPR's and MACRO's alike, as EXPR's 
% Instead, could check. 
END; 


[??? Mention CodeApply, LambdaApply, LambdaEvalApply, etc. 777] 


11.2. Support Functions for Eval and Apply 


EvLis (Usany-list): any-list expr 


EvLis returns a list of the evaluation of each element of U. 
Eval uses more efficient functions, hand-coded in LAP, to avoid 
the Conses. 


EvProgN (U:form-list): any expr 


Evaluates each form in U in turn, returning the value of the 


last. Used for various implied ProgNs. 


11.3. Special Evaluator Functions, Quote, and Function 


Quote (Usany): any fexpr 


Returns Car(U). Thus the argument is not evaluated by Eval. 
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MkQuote (Usany): list expr ES 


MkQuote(U) returns List('QUOTE, U) 


Function (FN:function): function fexpr 
The function FN is to be passed to another function. If FN is to oe 
have side effects its free variables must be FLUID or GLOBAL. 
Function is like Quote but its argument may be affected by 
compilation. -> 

[??? Add FQUOTE, and make FUNCTION become CLOSURE ???] 


See also the discussion of Closure and related functions in Section 10.3. 


11.4. Support Functions for Macro Evaluation 


Expand (L:list, FN:function): list expr 


FN is a defined function of two arguments to be used in the 
expansion of a macro. Expand returns a list in the form: 


(FN L[O] (FN L[1] ... (FN L{n-1] Lln]) ... )) 
"n" is the number of elements in L, Llil is the i'th element of 
L. 
EXPR PROCEDURE EXPAND(L,FN); 
IF NULL CDR L THEN CAR L 
ELSE LIST(FN, CAR L, EXPAND(CDR L, FN)); 


[??? Add RobustExpand (sure!) (document) ?77] 


[??? Add an Evalhook and Apply hook for CMU toplevel (document) ???] 


LJ 
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CHAPTER 12 
SYSTEM GLOBAL VARIABLES, FLAGS AND OTHER "HOOKS" 


12.1. Introduction 12.1 
12.2. Flags 12.1 
12.3. Globals 12.3 
12.4. Special Put Indicators 12.4 
12.5. Special Flag Indicators 12.5 
12.6. Displaying Information About Globals 12.6 


12.1. Introduction 


A number of global variables provide global control of the LISP system, 
or implement values which are constant throughout execution. Certain 
options are controlled by switches, with T or NIL properties (e.g. ECHOing 
as a file is read in); others require a value, such as an integer for the 
current output base. PSL has the convention (following the REDUCE/RLISP 
convention) of using a "!*" in the name of the variable: !*XXXXX for GLOBAL 
variables expecting a T/NIL value (called "flags"), and XXXXX!* for other 
GLOBALs. 


[??? These should all be FLUIDS, so that ANY one of these variables may 
be rebound, as appropriate ???] 


12.2. Flags 


This section contains a list of system flags used in PSL with references 
to chapters where they are defined. Strictly speaking, XXXX is a flag and 
!1*XXXX is a corresponding global variable that assumes the T/NIL value; 
both are loosely referred to as flags elSewhere in the manual. 


The On and Off functions are used to change the values of the variables 
associated with flags, and also to evaluate an s-expression (if present) 
stored under the SIMPFG indicator on the property list of XXXXX. The 
S-expression should have the form of a COND list: 


((T (action-for-0N)) (NIL (action-for-OFF) )) 


In LISP, use "(ON xxxx yyyy +... zzzz)" and "(OFF xxxx yyyy ... zzzz)". In 
RLISP, the On and Off functions have the syntax: 
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On XXXX, YYYY, du „ZZZZ 4 
and 
OFF XXXX,;, YYYY, «vx: LLL E 


On ([U:id]): None macro 


For each U, the associated !*U variable is set to T. Ifa "(T 
(action-for-0N))" clause is found by GET(U,'SIMPFG), the "action" 
is EVAL'ed. 


off ([U:id]): None macro 
For each U, the associated !*U variable is set to NIL. If a 


"(NIL (action-for-0N))" clause is found by GET(U,'SIMPFG), the 
"action" is EVAL'ed. 


! *BACKTRACE Chapter 15 
! * BREAK Chapter 15 
1*BTR Chapter 16 
!*BTRSAVE Chapter 16 
!*COMP Chapter 10 
!*COMPRESSING Chapter 13 
!*CREFSUMMARY Chapter 18 
!*DEFN Chapter 19 
t *ECHO Chapter 13 
! *EOLINSTRINGOK Chapter 13 
1*GC Chapter 22 
t *INSTALL Chapter 16 
!*INSTALLDESTROY Chapter 19 
INT Chapter 19 
!*MSGP | Chapter 15 
! *MODULE Chapter 19 
! *NOF RAMEFLUID Chapter 19 
! *NOLINKE Chapter 19 
!*NOTRARGS Chapter 16 
!*#ORD Chapter 19 
!*PECHO Chapter 14 
!*PGWD Chapter 19 
!*PLAP Chapter 19 
!*PVAL Chapter 14 
!*PWRDS Chapter 19 
!¥*R2T Chapter 19 
!*RATSE Chapter 13 
! *REDEFMSG Chapter 10 


!*SAVECOM Chapter 19 
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! *SAVEDEF 

! *SAVENAMES 

1 FSHOWDEST 
!*SYSLISP 
TIME 

1 *TRACE 
!*TRACEALL 
!*TRCOUNT 

! * TRUNKNOWN 

! *UNSAFEBINDER 
! *USEREGFLUID 
! *USERMODE 


12.3. Globals 


The fol 


lowing GLOBALs are 


\ CURRENT PACKAGE! * 
\PACKAGENAMES ! * 
BREAKIN! * 
BREAKOUT! * 
CURRENTSCANTABLE! * 
DF PRINT! * 

EMSG! * 

!SEOF!$ 

! $EOL! $ 

! $ERROR! $ 
ERRORFORM! * 
ERRORHANDLERS! * 
ERROUT! * 

GCKNT! * 

HELPIN!* 
HELPOUT!* 

IN! * 
LISPSCANTABLE!* 


` NOLIST!* 


OPTIONS!* 

OUT! * 

OUTPUTBASE! * 
PPFPRINTER!* 
PROMPTSTRING! * 
PROPERTYPRINTER!* 
PUTDHOOK!*: 
RLISPSCANTABLE! * 
SPECIALCLOSEFUNCTION! * 
SPECIALRDSACTION!*® 
SPECTIALREADFUNCTION!* 
SPECIALWRITEFUNCTION! * 


Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 


used mostly to 
communicate between various routines. 


Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 
Chapter 


6 

6 

15 
15 
13 
19 
15 
13 
13 
15 
15 


control 


15- 


13 
22 
13 
13 
13 
13 
18 
19 
13 
13 
16 
13 
16 
16 
13 
13 
13 
13 
13 


options 


Globals and Hooks 
page 12.3 


and to 
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SPECIALWRSACTION !* Chapter 13 
STDIN!* Chapter 13 
STDOUT1* Chapter 13 
STUBPRINTER!* Chapter 16 
STUBREADER! * Chapter 16 
SYSLISP!* Chapter 19 
TOKTYPE!* Chapter 13 
TOPLOOPEVAL!* Chapter 14 
TOPLOOPPRINT!* Chapter 14 
TOPLOOPREAD!* Chapter 14 
TRACEMINLE VEL! * Chapter 16 
TRACEMAXLEVEL! * Chapter 16 
TRACENTRYHOOK ! * Chapter 16 
TRACEXITHOOK!* Chapter 16 
TRACEXPANDHOOK! * Chapter 16 
TREXPRINTER!* Chapter 16 
TRINSTALLHOOK! * Chapter 16 
TRPRINTER!* Chapter 16 
TRSPACE! * Chapter 16 
NIL (Initially: NIL) global 
NIL is special GLOBAL variable. It is protected from being 


modified by Set or SetQ. 


T (Initially: T) global 


T is a special GLOBAL variable. It is protected from being 
modified by Set or SetQ. 


12.4. Special Put Indicators 


Some actions 


indicators: 


HelpFunction 


HelpString 


HelpFile 


search on the property list of relevant ids for these 


An id, a function to be executed to give help about the 
topic; ideally for a complex topic, a clever function is 
used. 


A help string, kept in core for important or short topics. 


The most common case, the name of a file to print; later we 
hope to load this file into an EMODE buffer for perusal in a 
window. 
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Flaginfo A string describing the purpose of the FLAG, see ShowFlags 
below. 

GlobalInfo A string describing the purpose of the GLOBAL, see 


ShowGlobals below. 


BreakFunction Associates a function to be run with an Id typed at Break 


Type 


Loop, see Chapter 15. 


PSL uses the property TYPE to indicate whether a function is 
a FEXPR, MACRO, or NEXPR; if no property is present, EXPR is 
assumed. 


!*LambdaLink The interpreter also looks under !*LambdaLink for a Lambda 


expression, if a procedure is not compiled. 


12.5. Special Flag Indicators 


'EVAL 


' IGNORE 


"LOSE 


"USER 


If the id is flagged EVAL, the RLISP top-loop evaluates and 
outputs any expression (id ...) in On Defn (!*DEFN := T) mode. 


If the id is flagged IGNORE, the RLISP top-loop evaluates but 
does NOT output any expression (id ...) in On Defn (!*DEFN := T) 
mode. 


If an id has the 'LOSE flag, it will not be defined by PutD when 
it is read in. 


'USER is put on all functions defined when in !*USERMODE, to 
distinguish them from "system" functions. See Chapter 10. 


See also the functions LoadTime and CompileTime in 
Chapter 19. 


[??? Mention Parser properties ??7] 
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12.6. Displaying Information About Globals 


The Help function has two options, HELP(FLAGS) and HELP(GLOBALS), which 
. should display the current state of a variety of flags and globals 
respectively. These calls have the same effect as using the functions 
below, using an initial table of Flags and Globals. 


The function ShowFlags(flag-list); may be used to print names, current 
settings and purpose of some flags. Use NIL as the flag-list to get 
information on ALL flags of interest; ShowFlags in this case does a MapQbl 
(Section 6.4.2) looking for 'FlagInfo property. 


Similarly, ShowGlobals(global-list); may be used to print names, values 
and purposes of important GLOBALs. Again, NIL used as the global-list 
causes ShowGlobals to do a MAPOBL looking for a 'GlobalInfo property; the 
result is some information about all globals of interest. 


y 


J 


CL 
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CHAPTER 13 
INPUT AND OUTPUT 


13.1. Introduction 13.1 
13.2. The Underlying Primitives for Input and Output 13.1 
13.3. Opening, Closing, and Selecting Channels 13.3 
13.4. Reading Functions 13.5 
13.5. Scan Table Utility Functions 13.11 
13.6. Procedures for Complete File Input and Output 13.11 
13.7. Printing Functions 13.13 
13.8. S-Expression Parser 13.17 

13.8.1. Read Macros 13.18 
13.9. I/O to and from Lists and Strings 13.18 
13.10. Example of Simple I/O in PSL 13.20 


13.1. Introduction 


Most LISP programs are written with no sophisticated I/O, so this chapter 
may be skimmed by. those with simple I/O requirements. Section 
13.10 contains an example showing the use of some I/O functions. This 
should heip the beginning PSL user get started. Sections 13.4 and 
13.5 deal extensively with customizing the scanner and reader, which is of 
interest only to the sophisticated user. 


13.2. The Underlying Primitives for Input and Output 


A11 input and output functions are implemented in terms of operations on 
1 ; 
"channels". A channel is just a small integer which has 3 functions and 
some other information associated with it. The three functions are: 


a. A reading function, which is called with the channel as its 
argument and returns the ASCII value of the next character of 
the input stream as an integer. If the channel is intended for 
writing only or has not been opened, an error is generated. 


1 
The range of channel numbers is from 0 to MaxChannels; MaxChannels is a 
system-dependent constant (currently 31). 
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b. A writing function, which is called with the channel as its 
first argument and the ASCII value of the character to be 
written as an integer as its second argument. If the channel is 
intended for reading only or has not been opened, an error is 
generated. 


C. A closing function, which is called with the channel as its 
argument and performs any action necessary for the graceful 
termination of input and/or output operations to that channel. 
If the channel is not open, an error is generated. 


The other information associated with a channel includes the current 
position in the output line (used by Posn), the maximum line length allowed 
(used by LineLength and the printing functions), the single character input 
backup buffer (used by the token scanner), and other system-dependent 
information. 


Ordinarily, the user need not be aware of the existence of this 
mechanism. However, because of its generality, it is possible to implement 
operations other than just reading from and writing to files using it. In 
particular, the LISP functions Explode and Compress are performed by 
writing to a list and reading from a list, respectively (on channels 3 and 
4 respectively). ; 


Ordinarily, user interaction with the system is done by reading from the 
standard input channel and writing to the standard output channel. These 
are 0 and 1 respectively, to which the GLOBAL variables STDIN!* and 
STDOUT! * are bound. These channels usually refer to the user's terminal, 
and cannot be closed. Other files are accessed by calling the function 
Open, which returns a channel. Most functions which perform ¡input and 
output come in two forms, one which takes a channel as its first argument, 
and one which uses the "currently selected channel". The functions Rds and 
Wrs are used to change the currently selected input and output channels. 
The GLOBAL variables IN!* and OUT!* are bound to these channels. 


GLOBAL variables containing information about channels are listed below. 


IN!* (Initially: 0) global 
Contains the currently selected input channel. This is changed 
by the function Rds. 

OUT!* (Initially: 1) global 


Contains the currently selected output channel. This is changed 
by the function Wrs. 


Displayed as a prompt when any input is taken from TTY. Thus 
prompts should not be directly printed. Instead the value should 
be bound to PROMPTSTRING!*, 


13.3. Opening, Closing, and Selecting Channels 


Open (FILENAME:string, ACCESSTYPE:id): CHANNEL:io-channel 


If ACCESSTYPE is Eq to INPUT or OUTPUT, an attempt: is made to 
access the system-dependent FILENAME for reading or writing. If 
the attempt is unsuccessful, an error is generated; otherwise a 
free channel is returned and initialized to the default 
conditions for ordinary file input or output. 


If ACCESSTYPE is Eq to SPECIAL and the GLOBAL variables 
SPECIALREADFUNCTION!*, SPECIALWRITEFUNCTION!*, and 
SPECIALCLOSEFUNCTION!* are bound to ids, then a free channel is 
returned and its associated functions are set to the values of 
these variables. Other non system-dependent status is set to 
default conditions, which can later be overridden. The functions 
ReadOnlyChannel and WriteOnlyChannel are available as error 
handlers. The parameter FILENAME is used only if an error 
occurs. 


If none of these conditions hold, a file is not available, or 
there are no free channels, an error is generated. 
#*¥***% Unknown access type 


#*%%% Improperly set-up special 10 open call 
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STDIN!* (Initially: 0) global 
The standard input channel. 

STDOUT!* (Initially: 1) global 
The standard output channel. 

ERROUT!* (Initially: 1) global 
The channel used by the ErrorPrintF. 

PROMPTSTRING!* (Initially: "lisp>") global 


expr 
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#£4¥% File not found 
**x%*%* No free channels 


One can use FileP to find out whether a file exists. 


FileP (NAME:string): boolean expr 


This function will return T if file NAME can be opened, and NIL 
if not, e.g. if it does not exist. 


Close (CHANNEL:io-channel): io-channel expr 
The closing function associated with CHANNEL is called, with 
CHANNEL as its argument. If it is illegal to close CHANNEL, if 
CHANNEL is not open, or if CHANNEL is associated with a file and 
the file cannot be closed by the operating system, this function 
generates an error. Otherwise, CHANNEL is marked as free and is 
returned. 


Rds ({CHANNEL:io-channel,NIL}): io-channel expr 


Rds sets IN!* to the value of its argument, and returns the 
previous value of IN!*. In addition, if SPECIALRDSACTION!* is 
non-NIL, it should be a function of 2 arguments, which is called 
with the old CHANNEL as its first argument and the new CHANNEL as 
its second argument. Rds(NIL) does the same as Rds(STDIN!*). 


Wrs ({CHANNEL:io-channel,NIL}): io-—channel expr 
Wrs sets OUT!* to the value of its argument and returns the 
previous value of OUT!*. In addition, if SPECIALWRSACTION!* is 
non-NIL, it should be a function of 2 arguments, which is called 
with the old CHANNEL as its first argument and the new CHANNEL as 
its second argument. Wrs(NIL) does the same as Wrs(STDOUT!*), 


The following GLOBALs are used by the functions in this section. 
SPECIALCLOSEFUNCTION!* (Initially: NIL) global 


SPECIALRDSACTION!* (Initially: NIL) global 
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SPECIALREADFUNCTION!* (Initially: NIL) 


SPECIALWRITEFUNCTION!* (Initially: NIL) 


SPECIALWRSACTION!* (Initially: NIL) 


13.4. Reading Functions 
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global 


global 


global 


The funetions described here pertain to the scanner and reader. Globals 
and flags used by these functions are defined at the end of the section. 


ChannelReadChar (CHANNEL:io-channel): character 


expr 


Reads one character from CHANNEL. All input is defined in terms 
of this function. If CHANNEL is not open or is open for writing 
only, an error is generated. If there is a non-zero value in the 
backup buffer associated with CHANNEL, the buffer is set to zero 


and the value returned. . Otherwise, 
associated with CHANNEL is called with CHANNEL as 
the value it returns is returned by ChannelReadChar. 


£*X%* Channel not open 


#*¥*%%4 Channel open for write only 


ReadChar (): character 


Reads one character from current input. 


EXPR PROCEDURE READCHAR(); 
CHANNELREADCHAR IN!*;- 


ReadCH (): id 


reading function 
argument, and 


expr 


expr 


Reads a single character id; it calls ReadChar, and then converts 


into an id using Int21D or MkID. 


ChannelUnReadChar (CHAN: io-channel, CH:character): Undefined expr 


Input backup function. CH is deposited in the backup buffer 


associated with CHAN. This function should be called only after 


Channel ReadChar is called without 
operations, since it is used by the token scanner. 


intervening input 
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UnReadChar (CH:character): Undefined expr 
Backup on current input channel. 


EXPR PROCEDURE UNREADCHAR CH; 
CHANNELUNREADCHAR(IN!%*, CH); 


ChannelReadToken (CHANNEL:io-channel): fid, number, string} expr 


This is the basic LISP token scanner. The value returned is a 
LISP item corresponding to the next token from the input stream. 
Ids are interned, unless the FLUID variable !*COMPRESSING is 
non-NIL. The GLOBAL variable TOKTYPE!* is set to: 


if the token is an ordinary id, 

if the token is a string, 

if the token is a number, or 

if the token is an unescaped delimiter. 


WN =0 


In the last case, the value returned is the id whose print name 
is the same as the delimiter. 


$ 


This function uses a vector bound to the FLUID variable 
CURRENTSCANTABLE!* to determine how various characters should be 
parsed. It has entries 0 ... 128 in it, one for each member of 
the ASCII character set (0 ... 127); the last entry is not a 
number, but rather an id which can be the Diphthong Indicator or 
the Read Macro Indicator. The following encoding is used. 


O ... 9 DIGIT: indicates the character is a digit, and gives 
the corresponding numeric value. 


10 LETTER: indicates that the character is a letter. 

11 DELIMITER: indicates that the character is a delimiter 
which is not the starting character of a diphthong. 

12 COMMENT: indicates that the character begins a comment 
terminated by end of line. 

13 DIPHTHONG: indicates that the character is a delimiter 


which may be the starting character of a diphthong. (A 
dinthong is a two character sequence read as one token, 
i.e., "<<" or MESE) 

14 IDESCAPE: indicates that the character is an escape 
character, to cause the following character to be taken 
as part of an id. (Ordinarily an exclamation point, 


i.e. wet) 
15 STRINGQUOTE: indicates that the character is a string 
quote. (Ordinarily a double quote, i.e. '"',) 


16 PACKAGE: indicates that the character is used to 
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introduce explicit package names. (Ordinarily "\".) 

17 IGNORE: indicates that the character is to be ignored. 
(Ordinarily BLANK, TAB, EOL and NULL.) 

18 MINUS: indicates that the character is a minus sign. 

19 PLUS: indicates that the character is a plus sign. 

20 DECIMAL: indicates that the character is a decimal 
point. 


If the function Read is called, CURRENTSCANTABLE!* is bound to 
the value of LISPSCANTABLE!* or to the value of 
RLISPSCANTABLE!* in RLISP. Embedded system builders who wish to 
use their own parsers can use this function for lexical scanning 
by binding an appropriate scan table to CURRENTSCANTABLE!*, 
Utility functions for building scan tables are described in the 
next Section. 


The following standards for scanning atoms are used. 


- Ids begin with a letter or any character preceded by an 
escape character. They may contain letters, digits and 
escaped characters. If !*RAISE is non-NIL, unescaped lower 
case letters are folded to upper case. The maximum size of 
an id (or any other token) is currently 5000 characters. 


Note: Using lower case letters in identifiers may cause 
portability problems. Lower case letters are automatically 
converted to upper case if the !*RAISE flag is T. This case 
conversion is done only for id input, not for single 
character or string input. 


[222 Can we retain input Case, but Compare RAISEd ???] 
[??? Permit - in ids ???] 
Examples: 
ThisIsALongIdentifier 
ThisIsALongIdentifierAndDifferentFromTheOther 


!*RAISE 
12222 


x we de k 


- Strings begin with a double quote (") and include all 
characters up to a closing double quote. A double quote can 
be included in a string by doubling it. An empty string, 
consisting of only the enclosing quote marks, is allowed. 
The characters of a string are not affected by the value of 
IXRATSE. Examples: 
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* "This is a string" 


* "This is a ""string""" 
% nu 


- Code-pointers cannot be input directly, but can be output 
and constructed. Currently printed as "#i#octal-address". 


- Integers begin with a digit, optionally preceded by a + or 
- sign, and consist only of digits. The GLOBAL input radix 
is 10; there is no way to change this. However, numbers of 
different radices may be read by the following convention. 
A decimal number from 2 to 36 followed by a sharp sign (#), 
causes the digits (and possibly letters) that follow to be 
read in the radix of the number preceding the #. Thus 63 may 
be entered as 8#77, or 255 as 16#ff or 16#FF. The Global 
output radix CAN be changed, by setting OUTPUTBASE!*, If 
OutPutBase!* is not 10, the printed integer appears with 
appropriate radix. Leading zeros are suppressed and a minus 
Sign precedes the digits if the integer is negative. 
Examples: 


* 100 
* 45234 l 
* -8/44 (equal to -36) 


(27? Should we permit trailing . in integers for 
compatibility with some LISPs and require digits on each 
side of . for floats ???] 


- Floats have a period and/or a letter "e" or "E" in them. 
Any of the following are read as floats. The value appears 
in the format [-]n.nn...nnE[-]mm if the magnitude of the 
number is too large or small to display in [-Jnnnn.nnnn 


format. The erossover point is determined by the 
implementation. In BNF, floats are recognized by the 
grammar: l 

<base> ::= <unsigned-integer>. | 


.<unsigned-integer>|¡ 
<unsigned-integer>.<unsigned-integer> 
<ebase> ::= <base>¡<unsigned-integer> 
<unsigned-float> ::= <base>| 
<ebase>e<Xunsigned-integer>| 
<ebase>»e-<unsigned-integer>| 
<ebase>»e+<unsigned-integer>| 
<ebase>E<unsigned-integer>| 
<ebase>E-<unsigned-integer>| 
<ebase>E+<unsigned-integer> 


J 


iJ 


J 
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<float> ¿2= <unsigned-float>| 
+<unsigned-float>| 
-<unsigned-float> 


That is: 


* [+!~][nnn]{. Innn{eiE}[+}-IJnnn 
* nnn. 

* nnn 

* nnn.nnn 


Examples: 


1e6 
ee 
es 
2.0 
-1.25E-9 


K A Mm kK 


RAtom (): {id, number, string} l expr 


EXPR PROCEDURE RATOM(); 
CHANNELREADTOKEN IN!*; 


[??? Should we bind CurrentScanTable!* for this function too 


???] 
!*COMPRESSING (Initially: NIL) flag 
If !*COMPRESSING is non-NIL, ChannelReadToken does not intern 
ids. : 
! *EOLINSTRINGOK (Initially: NIL) flag 


If !*EOLINSTRINGOK is non-NIL, the warning message 
#** STRING CONTINUED OVER END-OF-LINE 


is suppressed. 


IFRAISE (Initially: T) flag 


If !*RAISE is non-NIL, all characters input for ids through PSL 
input functions are raised to upper case. If !*RAISE is NIL, 
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characters are input as is. A string is unaffected by !*RAISE, 


CURRENTSCANTABLE!* (Initially: 
[17 11 11 11 11 11 11 11 11 17 17 11 17 17 11 11 11 11 11 11 11 


ome cee me kee ee | eee ae mem O A A A 
"amm mam eh ma | ee | i ee 
—_ me arr oa en 

OS 
A ee ee ee ee 


sE D 


_ RLISPDIPTHONG]) global 


CURRENTSCANTABLE!* is bound by the function Read. 


LISPSCANTABLE!* (Initially: 
[17 10 10 10 10 10 10 10 10 17 17 10 17 17 10 10 10 10 10 10 10 


A A A A ee AV a n AX A A q OE mum mean 

„em ee D 
enma nae a ee A n a e aA D A me D D A A Mn ar mes 
-ama aama m D eee D A A A A AA 
—— a a_n 


LISPDIPHTHONG])) 0 SSS global 


$ 


RLISPSCANTABLE!* (Initially: 
[17 11 11 11 11 11 11 11 11 17 17 11 17 17 11 11 11 11 11 11 11 


-nm aam a m a a na O D AD AD AD AD D S D D ee D D 
— m a eee ee A a D me eee ee 
asme TU E LO Ma a Aae å ee ee ee ee 

eee ee ee eee D S 
ee ee eee ee ee ee | 


—— i AS La a S| SS LU MA MEA A MES MAA MA MER Ma AE AAA mr Me 


RLISPDIPTHONG]) global 


OUTPUTBASE!* (Initially: 10) global 


This global can be set to control the radix in which integers are 
printed out. If the radix is not 10, the radix is given before a 
sharp sign, e.g. 8/20 is"20" in base 8, or 16. 


TOKTYPE!* (Initially: 3) global 
ChannelReadToken sets TOKTYPE!* to: 

if the token is an ordinary id, 

if the token is a string, 


if the token is a number, or 
if the token is an unescaped delimiter. 


Wh = O 


iJ 


LJ 
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In the last case, the value returned is the id whose print name 
is the same as the delimiter. 


13.5. Sean Table Utility Functions 


The following functions are provided to manage scan tables, in the 
READ-TABLE-UTILS module (use via LOAD READ-TABLE-UTIL): 


PrintScanTable (TABLE:vector): NIL expr 


Prints the entire scantable, gives the O ... 127 entries with the 
name of the character class. Also prints the indicators used for 
Diphthongs and Read Macros. 


[??? Make smarter, reduce output, use nice names for control 
characters, ala EMODE. ?7?] 


CopyScanTable (OLDTABLE: (vector, NIL}): vector expr 


Copies the existing scantable (or CURRENTSCANTABLE!* if given 
NIL). Currently GenSym()'s the indicators used for Diphthongs 
and Read macros. 


[??? Change when we use Property Lists in extra slots of the 
Scan-Table ???] ° 


PutDipthong (TABLE:vector, ID1:id, ID2:id, DIP:id): NIL expr 


Installs DIP as the name of the diphthong ID1 followed by ID2 in 
the given scan table. 


PutReadMacro (TABLE:vector, 1D1:id, FNAME:id): NIL expr 


Installs FNAME as the name of the Read macro function for the 
delimiter or diphthong ID1 in the given scan table, 


13.6. Procedures for Complete File Input and Output 


The following procedures are used to read complete files, by first 
calling Open, and then looping until end of file. Recall that file-names 
are strings, and therefore need string-quotes (') around file names. File 
names may be given using full system dependent file name conventions, 
including directories and sub-directories, "links" and "logical-device- 
names", as appropriate on the specific system. 
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DskIn ([U:string-list]): None Returned fexpr 


Enters a Read-Eval-Print loop on the contents of each of the 
files in U. DskIn expects LISP syntax. Use the following 
format: (DskIn "File" "File" ...). 


In ([U:string-list]): None Returned macro 


Does the same as DskIn but expects RLISP syntax. On the DEC-20, 
VAX and Apollo, the function In causes files with extension .LSP 
and .SL to be read as LISP files, not as RLISP. This is a great 
convenience in using both LISP and RLISP files. Because of this, 
it is best to use the extension .RED for RLISP files and use .LSP 
or .SL only for fully parenthesized LISP files. There are some 
system programs, such as TAGS on the DEC-20, which expect RLISP 
files to nave the extension .RED, 


If it is not desired to have the contents of the file echoed as 
it is input, either end the In command with a "$", as 


In "*INFILE" $ 


or else include the statement "Off ECHO;" in your file. 


Evin (L:List): None Returned expr 


L must be a list of strings that are filenames. Evin is the same 
as In except that it computes its arguments. 


Lapin (U:string): None Returned expr 


Reads a Single LISP file as "quietly" as possible, i.e., it does 
not echo or return values. Note that LapIn can be used only for 
LISP files. It ignores file extensions. Use (Load F1 F2 ...) to 
do a (LapIn "PL:Fi.LAP") or "PL:Fi.B" to load modules such as 
USEFUL, EDITOR, etc. 


Out (U:string): None Returned expr 


Opens file for output, redirecting standard output. 
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Shut (U:string): None Returned 


Closes the output file. 


expr 


For information about fast loading of functions with Fasl see Chapter 19. 


13.7. Printing Functions 


ChannelWriteChar (CHANNEL:io-channel, CH:character): character 


Write one character to CHANNEL. All output is defined in terms 
of this function. If CH is equal to char EOL (ASCII LF, 812) 
the line counter POSN associated with CHANNEL is set to zero. 


Otherwise, it is increased by one. The writing function 
associated with CHANNEL is called with CHANNEL and CH as its 
arguments. 


WriteChar (CH:character): character 
Write single character to current output. 
EXPR PROCEDURE WRITECHAR CH; 
_CHANNELWRITECHAR(OUT!*, CH); 
ChannelPrin1 (CHN:integer, ITM:any): ITM:any 
ChannelPrin1 is the basic LISP printing function. For 
well-formed, non-circular (non-self-referential) structures, the 
result can be parsed by the function Read. 
- Strings are printed surrounded by double quotes ("). 


- Delimiters inside ids are preceded by the escape character 


(!). 
- Floats are printed as {-}nnn.nnn{E{-}nn}. 


- Integers are printed as {-}nnn, unless the value of 
OUTPUTBASE!* is not 10, in which case they are printed as 
{-}ré#nnn; r is the value of OutPutBase!*. 


- Pairs are printed in list notation; that is, (a . (b . c)) 
is printed as (ab .c), and (a. (b . (e . NIL))) is 
printed as (a bec). 


- Vectors are printed in vector notation; a vector of three 


expr 


expr 


expr 
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elements a, b, and e is printed as [a b cl. 


Other items can be printed but cannot be parsed by Read. The 
elements of dotted pairs and lists are printed by recursive calls 
on ChannelPrini. Code-pointers are printed as #<Code:nnnn>; nnnn 
is the octal machine address of the entry point of the code 
vector. Anything else is printed as #<Unknown:nnnn>; nnnn is the 
octal value found in the argument register. Such items are not 
legal LISP entities and may cause garbage collector errors if 
they are found in the heap. 


Print (ITM:any): ITM:any expr 


EXPR PROCEDURE PRIN1 ITM; 
CHANNELPRIN1(OUT!*, ITM); 


ErrPrin (U:any): None Returned expr 
Prin1 with special quotes to highlight U. 
ChannelPrin2 (CHN:io-channel, ITM:any): ITM:any expr 


ChannelPrin2 is similar to ChannelPrin1, except that strings are 
printed without the surrounding double .quotes, and delimiters 
within ids are not preceded by the escape character. 


Prin2 (ITM:any): ITM:any expr 


EXPR PROCEDURE PRIN2 ITM; 
CHANNELPRIN2(OUT!*, ITM); 


Print (U:any): U:any expr 


Display U using Prin1 and terminate line. 


PrintF (FORMAT:string, [ARGS:any]): NIL expr 


PrintF is a simple routine for formatted printing, similar to the 
function with the same name in the C language[22]. FORMAT is 
either a LISP or SYSLISP string, which is printed on the 
currently selected output channel. However, if a % is 
encountered in the string, the character following it is a 
formatting directive, used to interpret and print the other 
arguments to PrintF in order. The following format characters 
are currently supported: 
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- For SYSLISP arguments, use: 


%d print the next argument as a decimal integer 

žo print the next argument as an octal integer 

$x print the next argument as a hexadecimal integer 
e print the next argument as a single character 

ys) print the next argument as a string 


~ For LISP tagged items, use: 


Sp print the next argument as a LISP item, using 


Print 

ZW print the next argument as a LISP item, using 
Prin2 

ar print the next argument as a LISP item, using 


ErrPrin (Ordinarily Prin2 """; Print Arg; Prin2 
nin ) 


%1 same as %¿w, except lists are printed without top 
level parens; NIL is printed as a blank 
e eval the next argument for side-effect -— most 


useful if the thing evaled does some printing 


Not using arguments: 


an print end-of-line character 


If the character following % is not either one of the above or 
another %, it causes an error. Thus, to include a % in the 
format to be printed, use 2%. 


There is no checking for correspondence between the number of 
arguments the FORMAT expects and the number given. If the number 
given is less than the number in the FORMAT string, then garbage 
will be inserted for the missing arguments. If the number given 
is greater than the number in the FORMAT string, then the extra 
ones are ignored. 


ErrorPrintF (FORMAT:string, [ARGS:any]): NIL 


ErrorPrintF is similar to PrintF, except that instead of using 
the currently selected output channel, ERROUT!* is used. Also, 
an end-of-line character is always printed after the message, and 
an end-of-line character is printed before the message if the 
line position of ERROUT!* is greater than zero. 


expr 
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TerPri (): NIL expr 


Terminate current OUTPUT line, and reset the POSN counter to 0. 


Eject (): NIL expr 


Skip to top of next output page. 


Posn (): integer expr 
Returns number of characters output on this line (i.e. POSN 
counter since last Terpri) 

LPosn (): integer expr 
[not implemented yet]Returns number of lines output on this page 
(i.e. LPosn counter since last Eject). 

LineLength (LEN: {integer, NIL)): integer expr 
Set maximum output line length if a positive integer, returning 
previous value. If NIL just return previous value. Controls the 
insertion of automatic Terpri's. 

RPrint (U:form): NIL expr 


Print in RLISP format. Autoloading. 


PrettyPrint (U:form): U expr 


Prettyprints U. Autoloading. 


Prin2L (L:any): L expr 
Prin2, except that a list is printed without the top level 
parens. 

Spaces (N:integer): NIL expr 


Prin2 N spaces. 
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Prin2T (X:any): any expr 


Prin2 and TerPri. 


Tab (N:integer): NIL expr 


Move to position N, emitting spaces as needed. TerPri() if past 
column N. 3 


13.8. S-Expression Parser 


ChannelRead (CHN:io-channel): any expr 


Returns the next expression from input channel CHN. Valid input 
forms are: vector notation, pair notation, list notation, 
numbers, code-pointers, strings, and identifiers with escape 
characters. Identifiers are interned (see the Intern function in 
Chapter 6), unless the FLUID variable !*COMPRESSING is non-NIL. 
ChannelRead returns the value of !$EOF!$ when the end of the 
currently selected input file is reached. ChannelRead has a 


CATCH('!$READ!$,'(ChannelReadWithHooks Channel)); 


call in its body, so that a Read can be aborted by a Throw with 
tag !$READ!$. This is in fact used to exit levels of Read when 
an end of file (!$EOF!$) is detected. 


ChannelRead uses the ChannelReadToken function, with tokens 
scanned according to the current sean table. In addition, Read 
macros are applied, if appropriate. The default reader uses the 
Read macro mechanism to do S-expression parsing: 


oo 


Starts a scan collecting S-expressions according to 
list or Dot notation until terminated by a ). A pair 
or list is returned. 


Starts a scan collecting S-expressions according to 
vector notation until terminated by a J]. A vector is 
returned. 


: Calls Read to get an S-expression, x, and then returns 
(Quote x). 


Input and Output 25 July 1982 PSL Manual 
page 13.18 section 13.8 


I$EOF!$ Does a Throw(!$READ!$, !$EOF!$) to rapidly exit a Read. 


E In some Read tables, { acts as a SuperParen, matched by 
"1. ) closes all pending (, upto a matching {. 


Read (): any expr 


Parse S-expression from current input. This does a 
ChannelRead(IN!*) after binding the fluid variable 
CURRENTSCANTABLE!* to LISPSCANTABLE!*, Thus Read always uses the 
LISP scan table. The user can define similar read functions for 
his own use with other scan tables. 


13.8.1. Read Macros 

A function of two arguments (Channel, Token) can be associated with any 
DELIMITER or DIPHTHONG token (i.e. those that have TOKTYPE!*=3) by calling 
PutReadMacro. <A ReadMacro function is called by ChannelReadTokenWithHooks 
if the appropriate token with TOKTYPE!*-3 is returned by ChannelReadToken. 
This function can then take over the reading (or scanning) process, finally 
returning a token (actually an S-expression) to be returned in place of the 
token itself. 


Example: The quote mark, 'x converting to (Quote x), is done by: 


PROCEDURE DOQUOTE(CHANNEL, TOKEN) ; 
LIST('QUOTE, CHANNELREAD(CHANNEL)); 


PUTREADMACRO(LISPSCANTABLE!*, '1' FUNCTION DOQUOTE) ; 
A ReadMacro is installed on the property list of the macro-character as a 
function under the indicators 'LISPREADMACRO, 'RLISPREADMACRO, etc. A 
Diphthong is installed on the property list of the first character as 


(second-character . diphthong) under the indicators 'LISPDIPHTHONG, 
'RLISPDIPHTHONG, etc. 


13.9. 1/0 to and from Lists and Strings 


Digit (U:any): boolean expr 


Returns T if U is a digit, otherwise NIL. 


pO 
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Liter (U:zany): boolean expr 
Returns T if U is a character of the alphabet, NIL otherwise. 

Explode (U:any): id-list expr 


Explode takes the constituent characters of an S-expression and 
forms a list of single character ids. It is implemented via the 
function ChannelPrin1, with a list rather than a file or terminal 


as destination. Returned is a list of interned characters 
representing the characters required to print the value of JU. 
Example: 


- Explode 'FOO; => (F O 0) 


- Explode '(A . B); => (!( A! ft, ! B!)) 
[??? add print macros. cf. UCI lisp ???] 


Explode2 (U:fatom}-{vector}): id-list 


Prin2 version of Explode. 


Compress (U:id-list): fatom}-{vector} 


U is a list of single character identifiers which is built into a 
PSL entity and returned. Recognized are numbers, strings, and 
identifiers with the escape character prefixing special 
characters. The formats of these items appear in the "Primitive 
Data Types" Section, Section 4.1.1. Identifiers are not interned 
on the OBLIST. Function pointers may not be compressed. If an 
entity cannot be parsed out of U or characters are left over 
after parsing an error occurs: 


¥#*£2%% Poorly formed atom in COMPRESS 


Implode (U:id-list): atom 


Compress with ids interned. 


FlatSize (U:any): integer 


Character length of Frin1 S-expression. 


expr 


expr 


expr 


expr 
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FlatSize2 (U:any): integer expr 


Prin2 version of flatsize. 


BldMsg (FORMAT:string, [ARGS:any]): string expr 


PrintF to string. BldMsg returns a string stating that the 
string could not be constructed if overflow occurs. 


13.10. Example of Simple 1/0 in PSL 


In the following example a list of S-expressions is read, one expression 
at a time, from a file STUFF.IN and is written to a file STUFF.OUT. The 
file EXAMPIO.RED contains the RLISP function TRYIO that makes this 
transfer. The files EXAMPIO and STUFF.IN were prepared using EMACS. 


Following is the contents of STUFF,IN, 


(r e d) 

(a b e) 
(1234) 
"ho ho ho" 
6.78 

5000 

XYZ 


The following shows the execution of the function TRYIO. 


PSLirlisp 

[Keeping rlisp] 

PSL 3.0 Rlisp, 8-Jul-82 

[1] In "EXAMPIO,RED"; 

Procedure Tryio (FIL1,FIL2); 

Begin Scalar OLDIN, OLDOUT, EXP; 
. OLDIN:=Rds Open(FIL1, 'input) ; 
OLDOUT:=Wrs Open(FIL2, 'output); ` 
While (EXP:=Read()) NEQ !$EOF!$ 

Do Print EXP; 

Close Rds OLDIN; 
Close Wrs OLDOUT; 

End;TRYIO 


NIL 
[2] Tryio ("STUFF.IN","STUFF.OUT") ; 
NIL 


Js 


e) 


cy) 
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[3] quit; 


The output file STUFF.OUT contains the following. 


(R E D) 

(A BC) 

(1 2 3 4) 
"ho ho ho" 
6.78 

5000 

XYZ 
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CHAPTER 14 
USER INTERFACE 
14.1. Introduction 14,1 
14.2. Stopping PSL and Saving a New Executable Core Image 14.1 
14.3. Changing the Default Top Level Function 14.2 
14.4. The General Purpose Top Loop Function 14.2 
14.5. The HELP Mechanism 14.5 
14.6. The Break Loop 14.6 
14.7. Terminal Interaction Commands in RLISP 14.6 


14.1. Introduction 


In this Section those functions are presented relating directly to the 
user interface; for example, the general purpose Top Loop function, the 
History mechanism, and changing the default Top Level function. 


14.2.. Stopping PSL and Saving a New Executable Core Image 


The normal way to stop PSL execution is to call the Quit function or to 
strike <Ctrl-C> on the DEC-20 or <Ctrl-Z> on the VAX. 


Quit (): Undefined expr 
Return from LISP to superior process. 


After either of these actions, PSL may be re-entered by typing START or 
CONTINUE to the EXEC on the DEC-20. After exiting, the core image may also 
be saved using the Tops-20 monitor command "SAVE filename". On the VAX, 
Quit causes a stop signal to be sent, so that PSL may be continued from the 
shell. 


A better way to exit and save the core image is to call the function 
SaveSysten. 


SaveSystem (MSG:string): Undefined expr 


This records the welcome message (after attaching a date) in the 
global variable LISPBANNNER!* used by StandardLisp's call on 
TopLoop, and then calls DumpLisp to compact the core image and 
write it out as a machine dependent executable file. In RLISP, 
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it sets USERMODE!* to T. 


If RLISP has been loaded, SaveSystem will have been redefined to 
save the message in global variable DATE!*, and redefine Main to 
call RlispMain, which uses DATE!* in Begin1. 


DumpLisp (): Undefined expr 


This calls Reclaim to compact the heap, and unmaps the unused 
pages (DEC-20) or moves various segment pointers (VAX) to 
decrease the core image. The core image is then written as an 
executable file, with name of global DUMPFILENAME!* (initially 
"PSL-SAVE.EXE" on the DEC-20 and "a.out" on the VAX). If 
desired, the user can then Quit and rename the file name, or 
change DUMPFILENAME!* before calling SaveSystem. 


Reset (): Undefined expr 


Return to top level of LISP. Equivalent to <Ctrl-C> and Start on 
DEC-20. 


14.3. Changing the Default Top Level Function 


As PSL starts up, it first sets the stack pointer and various other 
variables, and then calls the function Main inside a While loop, protected 
by a Catch. By default, Main calls a StandardLisp top loop, defined using 
the general TopLoop function, described in the next Section. In order to 
have a saved PSL come up in a different top loop, the Main should be 
appropriately redefined by the user (e.g. as is done to create RLISP). 


Main (): Undefined expr 


Initialization function, called after setting the stack. Should 
be redefined by the user to change the default TopLoop. 


14.4. The General Purpose Top Loop Function 


PSL provides a general purpose Top Loop that allows the user to specify 
his own Read, Eval and Print functions and otherwise obtain a standard set 
of services, such as Timing, History, Break Loop interface, and Interface 
to Help system. 


oy 
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TOPLOOPEVAL!* (Initially: NIL) global 


Tne Eval used in the current Top Loop. 


TOPLOOPPRINT!* (Initially: NIL) global 


The Print used in the current Top Loop. 


TOPLOOPREAD!* (Initially: NIL) global 


The Read used in the current Top Loop. 


TopLoop (TOPLOOPREAD!*:function, TOPLOOPPRINT!*:function, 


TOPLOOPEVAL!*:function, TOPLOOPNAME!*:id, WELCOMEBANNER:string): NIL - expr 


This function is called to establish a new Top Loop (currently 
used for Standard LISP, RLISP, and Break). It prints the 
WELCOMEBANNER and then invokes a "Read-Eval-Print" loop, using 
the given functions. Note that TOPLOOPREAD!*, etc. are FLUID 
variables, and so may be examined (and changed) within the 
executing Top Loop. TopLoop provides a standard History and 
timing mechanism, retaining on a list (HISTORYLIST!*) the input 
and output as a list of pairs. A prompt is constructed from 
TOPLOOPNAME!* and is printed out, prefixed by the History count. 
As a convention, the name is followed by a number of "5>"'s, 
indicating the loop depth. 


!*PECHO (Initially: NIL) . flag 
Causes parsed form read in top-loop StandardLisp to be printed, 
if T. l 

I*PVAL (Initially: T) flag 
Causes values computed in top-loop StandardLisp to be printed, if 
T. 

IXTIME (Initially: NIL) flag 


If on, causes a step evaluation time to be printed after each 
command. 
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Hist ([N:integer]): NIL nexpr 


This function does not work with the Top Loop used by psl:rlisp 
or by (beginrlisp); it does work with LISP and with RLISP if it 
is started from LISP using the (rlisp) function. Hist is called 
with 0, 1 or 2 integers, which control how much history is to be 
printed out: . 


(HIST) Display full history. 
(HIST n m) 
Display history from n to m. 
(HIST n) Display history from n to present. 
(HIST -n) Display last n entries. 


[??? Add more info about what a history is. ???] 


The following functions permit the user to access and resubmit previous 
expressions, and to re-examine previous results. 


Inp (N:integer): any expr 


Return N'th input at this level. 


ReDo (N:integer): any o | macro 


Reevaluate N'th input. 


Ans (N:integer): any expr 
Return N'th result. 


TopLoop has been used to define the following StandardLisp and RLISP top 
loops. 


StandardLisp (): NIL expr 
Interpreter LISP syntax top loop, defined as: 


LISP PROCEDURE STANDARDLISP(); 4%. Lisp top loop 
BEGIN SCALAR CURRENTREADMACROINDICATOR!*, 
CURRENTSC ANTABLE! *; 
CURRENTREADMACROINDICATOR!* :='LISPREADMACRO; 
CURRENTSCANTABLE!* := LISPSCANTABLE!*; 
TOPLOOP('READ, ‘PRINT, 'EVAL, "LISP", 
"PORTABLE STANDARD LISP"); 
end; 
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Note that the scan tables are modified. 


RLisp (): NIL expr 
Alternative interpreter RLISP syntax top loop, defined as: 
[??? xread described in RLISP Section 777] 


LISP PROCEDURE RLISP(); % RLisp top loop 
TOPLOOP('XREAD, 'PRINT, 'EVAL, 
"RLISP", "PSL RLISP"); 


Note that for the moment, the default RLISP loop is not this 
(though this may be used experimentally); instead a similar 
(special purpose hand coded) function, BeginRlisp, based on the 
Older Begini is used. It is hoped to change the RLISP top-level 
to use the general purpose capability. 


14.5. The HELP Mechanism 


PSL provides a general purpose Help mechanism, that is called in the 
TopLoop by invoking Help(); sometimes a ? may be used, as for example in 
the” break loop. 


Help ([TOPICS:id]): NIL fexpr 


If no arguments are given, a message describing Help itself and 
known topics is printed. Otherwise, each of the id arguments is 
checked to see if any help information is available. If it has a 
value under the property list indicator HelpFunction, that 
function is called. If it has a value under the indicator 
HelpString, the value is printed. If it has a value under the 
indicator HelpFile, the file is displayed on the terminal. By 
default, a file called "topic.HLP" on the Logical device, "PH:" 
is looked for, and printed if found. 


Help also prints out the values of the TopLoop fluids, and 
finally searches the current Id-Hash-Table for loaded modules. 


HELPIN!* (Initially: NIL) global 


The channel used for input by the Help mechanism. 
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HELPOUT!* (Initially: NIL) global 


The channel used for output by the Help mechanism. 


14.6. The Break Loop 


The Break Loop is described in detail in Chapter 15. For information, 
look there. 


14.7. Terminal Interaction Commands in RLISP 


Two commands are available in RLISP for use in interactive computing. 
The command PAUSE; may be inserted at any point in an input file. If this 
command is encountered on input, the system prints the message CONT? on the 
user's terminal and halts by calling YesP. 


YesP (MESSAGE:string): boolean . expr 


If the user responds Y or Yes, YesP returns T and the calculation 
continues from that point in the file. If the user responds N or 
No, YesP returns NIL and control is returned to the terminal, and 
the user can type in further commands. However, later on he can 
use the command CONT; and control is then transferred back to the 
point in the file after the last PAUSE was encountered. If the 
user responds B, one enters a break loop. After quitting the 
break loop, one still must respond Y, N, Yes, or No. 


J 


C 


J 
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CHAPTER 15 
ERROR HANDLING 


15.1. Introduction 15.1 
15.2. The Basic Error Functions 15.1 
15.3. Break Loop 15,3 
15.4. Interrupt Keys 15.6 
15.5. Details on the Break Loop 15.6 
15.6. Some Convenient Error Calls 15.7 
15.7. Special Purpose Error Handlers 15.8 


15.1. Introduction 


In PSL, as in most LISP systems, various kinds of errors are detected by 
functions in the process of checking the validity of their argument types 
and other conditions. Errors are then "signalled" to a currently active 
error handler (called ErrorSet) by a call on an Error function. In PSL, 
the error handler typically calls an interactive Break loop, which permits 
the user to examine the context of the error and optionally make some 
corrections and continue the computation, or to abort the computation. 


While in the Break loop, the user remains in the binding context of the 
function that detected the error; the user sees the value of FLUID 
variables as they are in the function itself. If the user aborts the 
computation, a call on Throw with a tag of! $ERROR!$ is done, and fluids are 
unbound. 


[??? What about errors signalled to the Interrupt Handler ???] 


15.2. The Basic Error Functions 


!®BACKTRACE (Initially: T) flag 
Set in ErrorSet. Controls whether an unwind backtrace is 
requested. 

I*MSGP (Initially: T) flag 


set in ErrorSet. Controls error message printing during call on 
error. 
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EMSG!# (Initially: NIL) ; global 


Contains the message generated by the last error call. 


ErrorSet (Usany, !*MSGP:boolean, !#*BACKTRACE:boolean): any expr 


If an uncorrected error occurs during the evaluation of U, the 
value of NUMBER from the associated error call is returned as the 
value of ErrorSet. Note that ErrorSet is an expr, so U gets 
evaluated twice, once as the parameter is passed and once inside 
ErrorSet. [Actually, ErrorSet executes a Catch with tag 
!$ERROR!$, and so intercepts any Throw with this tag.] In 
addition, if the value of !*MSGP is non-NIL, the message from the 
error call is displayed upon both the standard output device and 
the currently selected output device unless the standard output 
device is not open. The message appears prefixed with 5 
asterisks. The message list is displayed without top level 
parentheses. The message from the error call is available in the 
GLOBAL variable EMSG!*. The exact format of error messages 
generated by PSL functions described in this document may not be 
exactly as given and should not be relied upon to be in any 
particular form. Likewise, error numbers generated by PSL 
functions are not fixed. Currently, a number of different calls 
on Error result in the same error message, since the cause of the 
error is the same and the information to the user is the same. 
The error number is then used to indicate which function actually 
detected the error. 


[??? Describe Error # ranges here, or have in a file on 
machine ???] 


If no error occurs during the evaluation of U, the value of 
(List (Eval U)) is returned. 


If an error has been signalled and the value of !*BACKTRACE is 
non=NIL, a traceback sequence is initiated on the selected output 
device. The traceback displays information such as unbindings of 
FLUID variables, argument lists and so on in an implementation-- 
dependent format. 


Error (NUMBER:integer, MESSAGE:any): None Returned expr 


MESSAGE is placed in the GLOBAL variable EMSG!* and the error 
number becomes the value of the surrounding ErrorSet (if any 
intervening Break loop is exited). FLUID variables and LOCAL 
bindings are unbound to return to the environment of the 
ErrorSet. GLOBAL variables are not affected by the process. 
Error actually signals a non-continuable error to the Break loop, 
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and it subsequently does a throw with tag !$ERROR!$. 


ContinuableError (NUMBER:integer, MESSAGE:any, FORM:form): any expr 


MESSAGE is placed in the GLOBAL variable EMSG!* and the error 
number becomes the value of the surrounding ErrorSet if the 
intervening Break loop is "QUIT" rather than "Continued" or 
tRetried". FLUID variables and LOCAL bindings are unbound to 
return to the environment of the ErrorSet. GLOBAL variables are 
not affected by the process. Error actually signals a 
continuable error to the Break loop, and it subsequently does a 
throw with tag !$ERROR!$. 


The FORM is stored in the GLOBAL variable ERRORFORM!*, for 
examination, editing or possible reevaluation after defining 
missing functions, etc. Setting up the ERRORFORM!* can get a bit 
tricky, often involving MkQuoteing of already evaluated 
arguments. The following MACRO may be useful. 


ContError ([ARGS:any]): any macro 


The format of ARGS is (ErrorNumber, FormatString, {arguments to 
PrintF}, ReEvalForm). The FORMATSTRING is used with the 
following arguments in a call on BldMsg to build an error 
message. The ReEvalForm is something like Foo(X, Y) which 
becomes list('Foo, MkQuote X, MkQuote Y) to be passed to the 
function ContinuableError. 


[222 Give example, e.g. Divide in pi:easy-sl.red 277] 


15.3. Break Loop 


On detecting an error, PSL normally enters a Read/Eval/Print loop called 
a Break loop. Here the user can examine the state of his computation, 
change the values of FLUIDs, or define missing functions. He can then 
dismiss the error call to the normal error handling mechanism (the ErrorSet 
above) or (in some situations) continue the computation. By setting the 
flag !*BREAK to NIL, all Break loops can be suppressed. 


!*BREAK (Initially: T) flag 


Controls whether the Break package is called before unwinding the 
stack on error. 


The prompt "Break>" indicates that PSL has entered a Break loop. A 
message of the form "Continuation requires a value for ..." may also be 
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printed, in which case the user is able to continue his computation by 
repairing the offending expression. By default, a Break loop uses the 
functions Read, Eval, and Print. This may be changed by setting 
BREAKREADER!*#, BREAKEVALUATOR!*, or BREAKPRINTER!* to the appropriate 
function name. 


ERRORFORM! * (Initially: NIL) global 


Contains an expression to reevaluate inside a Break loop for 
continuable errors. [Not enough errors set this yet]. Used as a 
tag for various Error functions. 


Several ids, if typed at top-level, are special in a Break loop. These 
are used as commands, and are currently E, M, R, T, Q, I, and C. These are 
special only at top-level, and do not cause any difficulty if used as 


variables inside expressions. However, they may not be simply typed at 
top-level to see their values. This is not expected to cause any 
difficulty. If it does, an escape command will be provided for examining 


the relevant variables. 


The meanings of these commands are: 


E Edit the value of ERRORFORM!*. This is the object printed in the 
"Continuation requires a value for ..." message. The Retry 
command (below) uses the corrected version of ERRORFORM!*. The 
currently available editors are described in Chapter 17. 


M Show the modified ERRORFORM! *. 
R Retry. This tries to evaluate the offending expression again, 
and continue the computation. It evaluates the value of 


ERRORFORM!*. This is often useful after defining a missing 
function, assigning a value to a variable, or using the Edit 
command, above. l 


C This causes the expression last printed by the Break loop to be 
returned as the value of the offending expression. This is often 
useful as an automatic stub. If an expression containing an 
undefined function is evaluated, a Break loop is entered, and 
this may be used to return the value of the function call. 


Q Quit. This exits the Break loop by throwing to the closest 
surrounding ErrorSet. 


o) 
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T Trace. This prints a backtrace of functions call on the stack. 

I Interpreter Trace. This prints a backtrace of only interpreted 


functions call on the stack. 


InterpBackTrace (): Undefined expr 


Prints a backtrace of ONLY interpreted functions. Called by "I" 
in break loop. 


(22? Put this with backtrace? ???] 


An attempt to continue a non-continuable error with R or C prints a 
message and behaves as Q. 


The following is a slightly edited transcript, showing some of the BREAK 
options: 


% foo is an undefined function, so the following has two errors 
% in it 


1> foo(1)+fo0(2); 
**X*% “FOO' is an undefined function {1001} 
ERE Continuation requires a value for “(FOO 1)! 


Break loop 

1 lisp break> (plus2 1 1) % We simply compute a value 
2 % prints as 2 

2 lisp break> c % continue with this value 


% it returns to compute "foo(2)" 


#4#%*#*% “FOO' is an undefined function {1001} 
4###*%% Continuation requires a value for “(FOO 2)! 


Break loop 

1 lisp break> 3 % again compute a value 
3 

2 lisp break> c % and return 

5 % finally complete 


% Pretend that we had really meant to call "fee": 


2> procedure fee(x);x+1; 

FEE 

3> foo(1)+foo(2) ; % now the bad expression 
448% “FOO! is an undefined function {1001} 

4% Continuation requires a value for “(FOO 1)! 
Break loop 

1 lisp break> e % lets edit it 


Error Handling and Recovery 22 July 1982 PSL Manual 
page 15.6 section 15.3 


Type HELP<CR> for a list of commands. 


edit>p % print form 
(FOO 1) 
edit>(1 fee) % replace 1'st by "fee" 
edit>p % print again 
(FEE 1) 
edit>ok % we like it 
(FEE 1) 
2 lisp break> m % show modified ErrorForm! * 
ErrorForm!* : *(FEE 1)! 
NIL 
3 lisp break> r % Retry EVAL ErrorForm! * 


#*##2% “POO' is an undefined function {1001} 
£4%%% Continuation requires a value for “(FOO 2)! 


Break loop 

1 lisp break> (de foo(x) (plus2 x 1)) 4% define foo 
FOO 

2 lisp break> r 4 and retry 
5 


15.4. Interrupt Keys 
Need to "LOAD INTERRUPT;" to enable. This applies only to the DEC20. 


<Ctrl-T> indicates routine currently executing, gives the load average, 
and gives the location counter in octal; 


<Ctrl-G> returns you to the Top-Loop; 


<Ctrl-B> takes you into a lower-level Break loop. 


15.5. Details on the Break Loop 


If the FLAG !*BREAK is T, the function Break() is called by Error or 
ContinuableError before unwinding the stacks, or printing a backtrace. 
Input and output to/from Break loops is done from/to the values (channels) 
of BREAKIN!* and BREAKOUT!*. . The channels selected on entrance to the 
Break loop are restored upon exit. 


e) 


sd 


ud 
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BREAKIN!% (Initially: NIL) global 


So Rds chooses STDIN!*. 


BREAKOUT! * (Initially: NIL) global 
Similar to BREAKIN! *. 


Break is essentially a Read-Eval-Print function, called in the error 
context. Any FLUID may be printed or changed, function definitions 
changed, etc. The Break uses the normal TopLoop mechanism (including 
History), embedded in a Catch with tag !$BREAK!$. The TopLoop attempts to 
use the parent loop's TOPLOOPREAD!*, TOPLOOPPRINT!* and TOPLOOPEVAL!*; the 
BreakEval function first checks top-level ids to see if they have a special 
BREAKFUNCTION on their property lists, stored under 'BREAKFUNCTION. This 
is expected to a function of no arguments, and is applied instead of Eval. 


15.6. Some Convenient Error Calls 


The following functions may be useful in user packages: 


FatalError S; 
<<ErrorPrintF("***** Fatal error: $s", S); 
while T do Quit; >>; 


RangeError(Object, Index, Fn); 
StdError BldMsg("Index %r out of range for %p in %p", 
Index, Object, Fn); 


StdError Message; %. Error without number 
Error(99, Message); 


TypeError(Offender, Fn, Typ); 

StdError BldMsg("An attempt was made to do %p on fr, which is not $w", 

Fn, Offender, Typ); 

UsageTypeError(Offender, Fn, Typ, Usage); 

StdError 

BldMsg("An attempt was made to use fr as Zw in 4p, where Zw is needed", 

Offender, Usage, Fn, Typ); 

IndexError(Offender, Fn); 

UsageTypeError(Offender, Fn, "an integer", "an index"); 


NonPairError(Offender, Fn); 
TypeError(Offender, Fn, "a pair"); 


NonIDError(Offender, Fn); 
TypeError(Offender, Fn, "an identifier"); 
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NonNumberError(Offender, Fn); 
TypeError(Offender, Fn, "a number"); 


NonIntegerError(Offender, Fn); 
TypeError(Offender, Fn, "an integer"); 


NonPositivelntegerError(Offender, Fn); 
TypeError(Offender, Fn, "a non-negative integer"); 


NonCharacterError(Offender, Fn); 
TypeError(Offender, Fn, "a character"); 


NonStringError(Offender, Fn); 
TypeError(Offender, Fn, "a string"); 


NonVectorError(Offender, Fn); 
TypeError(Offender, Fn, "a vector"); 


NonSequenceError (Offend 
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PSL offers a small group of debugging functions in a mini-trace package 
described in Section 16.1.1; in addition, there is a separate debugging 


package which is the subject of the bulk of this Chapter. 


The PSL debugging package contains a selection of functions that can be 


1 
used to aid program development and to investigate faulty programs. 


1 


Much of this Chapter was adapted fgom a paper by Norman and Morrison. 
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It contains the following facilities. 


A trace package. This allows the user to see the arguments 
passed to and the values returned by selected functions. It is 
also possible to have traced interpreted functions print all the 
assignments they make with SetQ (see Section 16.2). 


- A backtrace facility. This allows one to see which of a set of 
selected functions were active as an error occurred (see Section 
16.4). 


- Embedded functions make it possible to do everything that the 
trace package can do, and much more besides (see Section 16.5). 


- Some primitive statistics gathering (see Section 16.6). 


- Generation of simple stubs. If invoked, procedures defined as 
stubs simply print their argument and read a value to return (see 
Section 16.7). 


- Some functions for printing useful information, such as property 
lists, in an intelligible format (see Section 16.8). 


- PrintX is a function that can print circular and re-entrant 
lists, and so can sometimes allow debugging to proceed even in 
the face of severe damage caused by the wild use of RplacA and 
RplacD (see Section 16.9). 


- A set of functions [:Car, ..., !:Cddddr, !:RplacA, !:RplacD and 
!sRplacW that behave exactly as the corresponding functions with 
the !: removed, except that they explicitly check that they are 
not used improperly on atomic arguments (see Section 16.10). 


- A collection of utility functions, not specifically intended for 
examining or debugging code, but often useful (see Section 
16.10). 


16.1.1. Mini-Trace Facility 

A small trace package is provided in the small core PSL and RLISP. This 
provides a command Tr for tracing LISP function calls, as does the full 
Debug package. This command and the associated command UnTr are used in 
the form: 


Tr <function name>, <function name>,..., <function name>; 
or 
Tr( <function name>, <function name>,..., <function name>); 


from RLISP, and 
(Tr <function name> <function name> ... <function name>) 
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from LISP. 


Tr ([FNAME:id]): Undefined 


UnTr ([FNAME:id]): Undefined 


Mini-Trace also provides a crude BREAKFN capability, 
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fexpr 


fexpr 


that causes the 


modified functions to call Break before and after execution of the function 


bodys: 


Br <function name>, <function name>,..., <function name>; 


or 


Br( <function name>, <function name>,..., <function name>); 


from RLISP, and 
(Br <function name> <function name> ... <function name>) 
from LISP. 


Br ([FNAME:id]): Undefined 


UnBr ([FNAME:id]): Undefined 


Do HELP(TRACE); for more information. 
16.1.2. Step 


Step (F:form): any 


fexpr 


fexpr 


Step is a loadable option (LOAD STEP;). Evaluates form, 
single-stepping. F is printed, preceded by -> on entry, <-> for 
macro expansions. After evaluation, F is printed preceded by 
<- and followed by the result of evaluation. A single character 
is read at each step to determine the action to be taken: 


<Ctrl=-N> (Next) 


Step to the Next thing. The stepper continues until 
the next thing to print out, and it accepts another 


command. 


Space Go to the next thing at this level. In other words, 
continue to evaluate at this level, but don't. step 
anything at lower levels. This is a good way to skip 
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over parts of the evaluation that don't interest you. 


<Ctrl-U> (Up) l 
Continue evaluating until we go up one level. This is 
like the space command, only more so; it skips over 
anything on the current level as well as lower levels. 


<Ctrl-X> (eXit) 
Exit; finish evaluating without any more stepping. 


<Ctrl-G> or <Ctrl-P> (Grind) 
Grind (i.e. prettyprint) the current form. 


<Ctrl-R> Grind the form in Rlisp syntax. 


<Ctrl-E> (Editor) 
Invoke the structure editor on the current form. 


<Ctrl-B> (Break) 
Enter a break loop from which you can examine the 
values of variables and other aspects of the current 
environment. 


<Ctrl-L> Redisplay the last 10 pending forms. 
? Display the heip file. 


16.1.3. Brief Summary of Full DEBUG Package 

Useful diagnostic information can often be obtained by observing the 
values which variables acquire during assignments in particular functions. 
To do this in PSL one uses the command Trst. There are some restrictions 
on the function names which appear in the arguments of this function, 
however. First, the functions must obviously be in the system in symbolic 
form; compiled functions no longer contain information on the assignment 
variable names. Secondly, the functions must have a compound statement at 
their top level. 


This particular trace may be turned off by the command UnTrst. 


Both Trst and Untrst are used in the same way as Tr. 
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!*NOTRARGS (Initially: NIL) flag 
Control arg-trace. T suppresses printing of the arguments of 


traced functions. 


16.1.4. Use 
To use do LOAD Debug;. The saved PSL may have this already loaded by 
default. 


16.1.5. Functions Which Depend on Redefining User Functions 

A number of facilities in Debug depend on redefining user functions, so 
that they may log or print behavior if called. The Debug package tries to 
redefine user functions once and for all, and then keep specific 
information about what is required at run time in a table. This allows 
considerable flexibility, and is used for a number of different facilities, 
including trace/traceset in Section 16.2, a backtrace facility in Section 
16.4, some statistics gathering in Section 16.6 and EMB functions in 
Section 16.5. 


Some, like trace and EMB, only take effect if further action is requested 
on specific user functions. Others, like backtrace and statistics, are of 
a more global nature. Once one of these global facilities is enabled it 
applies to all functions which have been made "known" to Debug. To undo 
this, use Restr in Section 16.2.3. 


16.1.6. Special Considerations for Compiled Functions 
All functions in Debug which depend on redefining user functions must 
make some assumptions about the number of arguments. The Debug package is 
able to find the correct names for the arguments of interpreted functions. 
If Debug can not find out for itself how many arguments a function has, it 
interactively asks for assistance. In reply to the question 
HOW MANY ARGUMENTS DOES xxxx HAVE? 


valid replies are: 


? ask for assistance 


UNKNOWN give up 


<number> specify the number of arguments 


(name ...) 
give the names of arguments. 
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[?2?2? How about a push to a new command level so one can look around and 
then come back to answer the question ???] 


If you give an incorrect answer to the question, the system may misbehave 
in an arbitrary manner. There can be problems if the answer UNKNOWN is 
given and subsequently functions get redefined or recompiled - if at all 
possible find out how many arguments are taken by the function that you 
wish to trace. 


It is possible to suppress the argument number query with 
ON TRUNKNOWN 
This is equivalent to always answering "UNKNOWN". 


[22?2? Add feature to enable compiled code to store argument names, etc. 
in LAP files ???] 


16.1.7. A Few Known Deficiencies 


- An attempt to trace certain system functions (e.g. Cons) causes 
the trace package to overwrite itself. Given the names of 
functions that cause this sort of trouble it is fairly easy to 
change the trace package to deal gracefully with them - so report 
trouble to a system expert. 


- The Portable LISP Compiler uses information about registers which 
certain system functions destroy. Tracing these functions may 
make the optimizations based thereon invalid. The correct way of 
handling this problem is currently under consideration. In the 
mean time you should avoid tracing any functions with the ONEREG 
or TWOREG flags. 


16.2. Tracing Function Execution 


Tr ([FNAME:id]): Undefined expr 


Trst ([FNAMEsid]): Undefined expr 


To see when a function gets called, what arguments it is given and what 
value it returns, do 


TR functionname; 


or if several functions are of interest, 
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TR name 1,name2,...; 


If the specified functions are defined (as expr, fexpr or macro), this 
REDUCE statement modifies the function definition to include print 
statements. The following example shows the style of output produced by 
this sort of tracing: 


The input... 


SYMBOLIC PROCEDURE XCDR A; 

CDR A; $ A very simple function; 
TR XCDR; 
XCDR '(P Q R); 


gives output... 


XCDR entered 
A: (P Q R) 
XCDR = (Q R) 


Interpreted functions can also be traced at a deeper level. 


TRST namel,name2...; i 
causes the body of an interpreted function to be redefined so that all 
assignments (made with SetQ) in its body are printed. Calling Trst on a 
function automatically has the effect of doing a Tr on it too, and the use 
of UnTr automatically does an UnTrst if necessary in Section 16.2.3, so 
that it is not possible to have a function subject to Trst but not Tr. 


Trace output often appears mixed up with output from the program being 
studied, and to avoid too much confusion Tr arranges to preserve the column 
in which printing was taking place across any output that it generates. If 
trace output is produced as part of a line has been printed, the trace data 
are enclosed in markers '<' and '>', and these symbols are placed on the 
line so as to mark out the amount of printing that had occurred before 
trace was entered. 


16.2.1. Saving Trace Output 


NewTrBuff (N:integer): Undefined expr 
TrOut ([FNAME:id]): Undefined expr 
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StdTrace (): Undefined expr 


The trace facility makes it possible to discover in some detail how a 
function is used, but in certain cases its direct use results in the 
generation of vast amounts of (mostly useless) print-out. There are 
several options. One is to make tracing more selective (see Section 
16.2.2). The other, discussed here, is to either print only the most 
recent information, or dump it all to a file to be perused at leisure. 


Debug has a ring buffer in which it saves information to reproduce the 
most recent information printed by the trace facility (both Tr and Trst). 
To see the contents of this buffer use Tr without any arguments 


TR; 


To set the number of entries retained to n use 
NEWTRBUFF (n); 


It is initially set to 5. 


Turning off the TRACE flag 

OFF TRACE; 
suppresses the printing of any trace information at run time; it is still 
saved in the ring buffer. Thus a useful technique for isolating the 
function in which an error occurs is to trace a large number of candidate 


functions, do OFF TRACE and after the failure look at the latest trace 
information by calling Tr with no arguments. 


Normally trace information is directed to the standard output, rather 
than the currently selected output. To send it elsewhere use the statement 
TROUT filename; 
The statement 
STDTRACE; 
closes that file and cause future trace output to be sent to the standard 


output. Note that output saved in the ring buffer is sent to the currently 
selected output, not that selected by Trout. 


—4 
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16.2.2. Making Tracing More Selective 
TraceCount (N:integer): Undefined expr 


Trin ({FNAME:id]): Undefined expr 


The function TraceCount(n) can de used to switch off trace output. If n 
is a positive number, after a call to TraceCount(n) the next n items of 
trace output that are generated are not printed. TraceCount(n) with n 
negative or zero switches all trace output back on. TraceCount( NIL) 
returns the residual count, i.e. the number of additional trace entries 
that are suppressed. 


Thus to get detailed tracing in the stages of a calculation that lead up 
to an error, try 


TRACECOUNT 1000000; % or some other suitable large number 
TR ....; % as required 

% run the failing problem 

TRACECOUNT NIL; 


It is now possible to calculate how many trace entries occurred before the 
error, and so the problem can now be re-run with TraceCount set to some 
number slightly less than that. 


An alternative to the direct of TraceCount is Trin. To use Trin, 
establish tracing for a collection of functions, using Tr in the normal 
way. Then do TrIn on some small collection of other functions. The effect 
is just as for Tr, except that trace output is inhibited except if control 
is dynamically within the TrIn functions. This makes it possible to use Tr 
on a number of heavily used general purpose functions, and then only see 
the calls to them that occur within some specific sub-part of your entire 
program. UnTr undoes the effect of Trin in Section 16.2.3. 


TRACEMINLEVEL!* (Initially: 0) global 


In DEBUG package. 


TRACEMAXLEVEL! * (Initially: 1000) global 
In DEBUG package. 


The global variables TRACEMINLEVEL!* and TRACEMAXLEVEL!* (which should be 
non-negative integers) are the minimum and maximum depths of recursion at 
which to print trace information. Thus if you only want to see top level 
calls of a highly recursive function (like a simple-minded version of 
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Length) simply do 


TRACEMAXLEVEL!* s= 1; 


16.2.3. Turning Off Tracing 


UnTr ({FNAME:id]): Undefined expr 
Restr ([FNAME:id]): Undefined expr 
UnTrst ([FNAME:id]): Undefined expr 


1f a particular function no longer needs tracing, do 

UNTR functionname; 
or 

UNTR namel,name2...; 
This merely suppresses géneration of trace output. Other information, such 
as invocation counts, backtrace information, and the number of arguments is 
retained. Thus UnTr followed later by Tr does not have to enquire about 
the number of arguments. 

To completely destroy information about a function use 


RESTR name1,name2...}3 


This returns the function to it's original state. 


To suppress traceset output without suppressing normal trace output use 
UNTRST namel,name2...; 


UnTring a Trsted function also UnTrst's it. 


TrIn in Section 16.2.2 is undone by UnTr (but not by UnTrst). 
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16.2.4. Automatic Tracing of Newly Defined Functions 
Under the influence of 


ON TRACEALL; 
any functions successfully defined by PutD are traced. Note that if PutD 


fails (as might happen under the influence of the LOSE flag) no attempt is 
made to trace the function. 


To enable those facilities (such as Btr in Section 16.4 and TrCount in 
Section 16.6) which require redefinition, but without tracing, use 


ON INSTALL; 


Thus, a common scenario might look like 
ON INSTALL; 

IN MYFNS.RED$ 

OFF INSTALL; 


which would enable the backtrace and statistics routines to work with all 
the functions defined in MYFNS.RED. 


o 


I*INSTALL (Initially: NIL) | flag 


In DEBUG package. Causes DEBUG to know about all functions 
defined with PutD. 


!*TRACEALL (Initially: NIL) flag 


In DEBUG package. Causes all functions defined with PutD to be 
traced. 


16.3. Automatic BREAK Around Functions 


[222 Install a feature BR and UNBR to wrap a break around functions. 
See mini-trace ???] 


16.4. A Heavy Handed Backtrace Facility 
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Btr ([FNAME:id]): Undefined expr 
ResBtr ([FNAME:id]): Undefined expr 


BTR £1,f2,...; 


arranges that a stack of functions entered but not left is kept - this 
stack records the names of functions and the arguments that they were 
called with. If a function returns normally the stack is unwound. If 
however the function fails, the stack is left alone by the normal LISP 
error recovery processes. 


To print this information call Btr without any arguments 
BTR; 


Calling Btr on new functions resets the stack. This may also be done by 
explicitly calling ResBtr 


RESBTR; 


The disposition of information about functions which failed within an 
ErrorSet is controlled by the !*BTRSAVE. ON BTRSAVE causes them to be 
saved separately, and printed when the stack is printed; OFF BTRSAVE causes 
them to be thrown away. 


OFF BTR suppresses saving of any Btr information. Note that any traced 
function has its invocations pushed and popped by the Btr mechanism. 


16.5. Embedded Functions 


Embedding means redefining a function in terms of its old definition, 
usually with the intent that the new version does some tests or printing, 
uses the old one, does some more printing and then returns. If ff isa 
function of two arguments, it can be embedded using a statement of the 
form: 


SYMBOLIC FMB PROCEDURE ff(A1, A2); 
<< PRINT A1; “+ 
PRINT A2; 
PRINT ££(A1,A2) >>; 


The effect of this particular use of embed is broadly similar to a call Tr 
ff, and arranges that whenever ff is called it prints both its arguments 
and its result. After a function has been embedded, the embedding can be 
temporarily removed by the use of 
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UNEMBED ff; 
and it can be reinstated by 


EMBED ff; 


16.6. Counting Function Invocations 


If the flag TRCOUNT is ON the number of times user functions known to 
Debug are entered is counted. The statement 


ON TRCOUNT; 
also resets that count to zero. The statement 
OFF TRCOUNT; 


causes a simple histogram of function invocations to be printed. To make 
Debug aware of a function use 


TRCNT namel,name2,...3 


See also Section 16.2.4. 


TrCnt ([FNAME:id]): Undefined expr 


16.7. Stubs 
Stub (FN:id): expr 


FStub (FN:id): expr 
The statement 
STUB FOO(U,V); 
defines an expr, Foo, of two arguments. If executed such a stub prints its 


arguments and reads a value to return. FStub is used to define fexprs. 
This is often useful in developing programs in a top down fashion. 


At present the currently (i.e. when the stub is executed) selected input 
and output are used. This may be changed in the future. Algebraic and 
possibly macro stubs may be implemented in the future. 
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16.8. Functions for Printing Useful Information 


PList ([X:id]): expr 
Ppf ([FNAME:id]): expr 


PLIST id1,id2,+...; 
prints the property lists of the specified ids. 
PPF fn1,fn2,+...; 


prints the definitions and other useful information about the specified 
functions. 


16.9. Printing Circular and Shared Structures 


PrintX (A:any): NIL expr 


Some LISP programs rely on parts of their data structures being shared, 
so that an Eq test can be used rather than the more expensive Equal one. 
ther programs (either deliberately or by accident) construct circular 
lists through the use of RplacA or RplacD. Such lists can be displayed by 
use of the function PrintX. WARNING: This function does NOT work for 
circular vectors! See Section 18.10 for functions dealing with circular 
vectors. If given a normal list the behavior of this function is similar 
to that of Print - if it is given a looped or re-entrant data structures it 
prints it in a special format. The representation used by PrintX for 
re-entrant structures is based on the idea of labels for those nodes in the 
structure that are referred to more than once. Consider the list created 
by the operations: 


:=NIL + NIL; % make a node 
RPLACA(A,A)3; RPLACD(A,A); % point it at itself 


If PrintX is called on the list A it discovers that the node is referred to 
repeatedly, and invents the label 4L1 for it. The structure is then 
printed as 


$L1: (L1 . $L1) 
%L1: sets the label, and the other instances of ¿L1 refer back to it. 


Labeled sublists can appear anywhere within the list being printed. Thus 
the list B := 'X . A; could be printed as 
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(X . L1: (2L1 . $L1)) 


This use of dotted pair representation is often clumsy, and so it gets 
contracted to 


(X @L1, @L1 . 211) 


A label set with a comma (rather than a colon) is a label for part of a 
list, not for the sublist. 


16.10. Library of Useful Functions 


Debug contains a library of utility functions which may be useful to 
those debugging code. The collection is as yet very small. suggestions 
for further functions to be in corporated are definitely solicited. 


16.11. Internals and Customization 


This Section describes some internal details of the Debug package which 
may be useful in customizing it for specific applications. 


The reader is urged to consult the source for further details. 


16.11.1. User Hooks 
These are all global variables whose value is normally NIL. If non-NIL 


they should be exprs taking the number of variables specified, and are 
called as specified. 


PUTDHOOK!* (Initially: NIL) global 


Takes one argument, the function name. It is called after the 
function has been defined, and any tracing under the influence of 
!*#TRACEALL or !*INSTALL has taken place. It is not called if the 
function cannot be defined (as might happen if the function has 
been flagged LOSE). 


TRACENTRYHOOK!* (Initially: NIL) global 


Takes two arguments, the function name and a list of the actual 
arguments. It is called by the trace package if a traced 
function is entered, but before it is executed. The execution of 
a surrounding EMB function takes place after TRACENTRYHOOK!* is 
called. This is useful if you need to call special user-provided 
print routines to display critical data structures, as are 
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TRACEXITHOOK!* and TRACEXPANDHOOK! *. 


TRACEXITHOOK! * (Initially: NIL) global 
Takes two arguments, the function name and the value. It is 
called after the function has been evaluated. 

TRACEXPANDHOOK!* (Initially: NIL) global 
Takes two arguments, the function name and the macro expansion. 

It is only called for macros, and is called after the macro is 
expanded, but before the expansion has been evaluated. 

TRINSTALLHOOK! * (Initially: NIL) global 
Takes one argument, a function name. It is called if a function 


is redefined by the Debug package, as for example when it is 
first traced. It is called before the redefinition takes place. 


16.11.2. Functions Used for Printing/Reading l 
These should all contain EXPRS taking the specified number of arguments. 
The initial values are given in square brackets. 


PPFPRINTER!* (Initially: PRINT) global 


Takes one argument. It is used by Ppf to print the body of an 
interpreted function. 


PROPERTYPRINTER!* (Initially: PRETTYPRINT) global 
Takes one argument. It is used by PList to print the values of 
properties. 

STUBPRINTER!* (Initially: PRINTX) global 


Takes one argument. Stubs defined with Stub/FStub use it to 
print their arguments. 


STUBREADER!* (Initially: !-REDREADER) global 


Takes no arguments. Stubs defined with Stub/FStub use it to read 
their return value. 
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TREXPRINTER!* (Initially: PRINT) global 
Takes one argument. It is used to print the expansions of traced 
macros. 

TRPRINTER! * (Initially: PRINTX) global 


Takes one argument. It-is used to print the arguments and values 
of traced functions. 


TRSPACE! * (Initially: 0) global 
Controls indentation. 
16.11.3. Flags 
These are all flags which can be set with the Reduce/Rlisp ON/OFF 


statements. Their initial setting is given in square brackets. Many have 
been described above, but are collected here for reference. 


!*BTR (Initially: T) flag 


enables backtracing of functions which the Debug package has been 
told about. ; 


!¥BTRSAVE (Initially: T) flag 


causes backtrace information leading up to an error within an 
errorset to be saved. 


!¥SAVENAMES (Initially: NIL) flag 
!¥TRACE (Initially: T) flag 


enables runtime printing of trace information for functions which 
have been traced. 
! *TRUNKNOWN (Initially: NIL) flag 


instead of querying the user for the number of arguments to a 
compiled EXPR, just assumes the user says "UNKNOWN". 
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IWTRCOUNT (Initially: T) flag 


enables counting invocations of functions known to Debug. Note 
that ON TRCOUNT resets the count, and OFF TRCOUNT prints a simple 
histogram of the available counts. 


16.12. Example 


This contrived example demonstrates many of the available features. It 
is a transcript of an actual REDUCE session. 


FOR HELP, TYPE HELP<ESCAPE> 


13 
2: LOAD DEBUG; 


SYMBOLIC PROCEDURE FOO N; 
BEGIN SCALAR A; 
IF REMAINDER(N,2) NEQ 0 AND N < O THEN 
A t= 1:CAR N; % Should err out if N is a number 
IF N = O THEN 
RETURN ‘BOTTOM; 


-2; 
LIST(A,BAR N,A) 


W Ww WW WW WW Www Ww 
ee ee ee ee ee ee oe ee so .. ee 


bj 
Íoz»z 
O Gun 


FOO 


4: SYMBOLIC PROCEDURE FOOBAR N; 
l; << FOO N; NIL>>; 


FOOBAR 

5: SYMBOLIC OPERATOR FOOBAR; 
NIL 

6: TR FOO, FOOBAR; 

(FOO FOOBAR) 


T: PPF FOOBAR, FOO; 


EXPR procedure FOOBAR(N) [Traced;Invoked 0 times;Flagged: OPFN]: 
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<<FOO N; NIL>>; 


EXPR procedure FOO(N) [Traced;Invoked 0 times]: 
BEGIN SCALAR A; 
IF NOT REMAINDER(N,2)=0 AND N<O THEN A s= !:CAR N; 
IF N=0 THEN RETURN 'BOTTOM; 
N := N -= 2; 
:= B 
:= N - 2; 
RETURN LIST(A,BAR N,A) 
FOOBAR( FOO) 
8: ON COMP; 


9: SYMBOLIC PROCEDURE BAR N; 

9: IF REMAINDER(N,2)=0 THEN FOO(2*(N/4)) ELSE FOO(2*(N/4)-1); 
** BAR 164896 BASE 20 WORDS 63946 LEFT 

BAR 

10: OFF COMP; 


11: FOOBAR 8; 
FOOBAR being entered 
Ns 8 
FOO being entered 
N: 8 
FOO (level 2) being entered 
Ns 2 
FOO (level 3) being 2ntered 
N: 0 
FOO (level 3) = BOTTOM 
FOO (level 3) being entered 
Ns 0 
FOO (level 3) = BOTTOM 
FOO (level 2) = (BOTTOM BOTTOM BOTTOM) 
FOO (level 2) being entered 
N: 2 
FOO (level 3) being entered 
N: 0 
FOO (level 3) = BOTTOM 
FOO (level 3) being entered 
N: 0 
FOO (level 3) = BOTTOM 
FOO (level 2) = (BOTTOM BOTTOM BOTTOM) 
FOO = (%4L1: (BOTTOM BOTTOM BOTTOM) (BOTTOM .BOTTOM BOTTOM) 
4L1) | 
FOOBAR = NIL 
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12: % Notice how in the above PRINTX printed the return values 
12: % to show shared structure 
12: TRST FOO; 


(FOO) 


13: FOOBAR 8; 
FOOBAR being entered 
N: 8 
FOO being entered 
N: 8 


FOO (level 2) being entered 
N: 2 
N := 
FOO (level 3) being entered 
N: 0 
FOO (level 3) = BOTTOM 


FOO (level 3) being entered 
Ns 0 
FOO (level 3) = BOTTOM 
FOO (level 2) = (BOTTOM BOTTOM BOTTOM) 


A := (BOTTOM BOTTOM BOTTOM) 
N := 4 
FOO (level 2) being entered 
: 2 
N ss 
FOO (level 3) being entered 
Ns O é 
FOO (level 3) = BOTTOM 
A := BOTTOM 
N 32 -2 
FOO (level 3) being entered 
N: 0 


FOO (level 3) = BOTTOM 
FOO (level 2) = (BOTTOM BOTTOM BOTTOM) 
FOO = (%L1: (BOTTOM BOTTOM BOTTOM) (BOTTOM BOTTOM BOTTOM) 
24L1) 
FOOBAR = NIL 
0 
14: TR BAR; 


*** How many arguments does BAR take ? 1 


(BAR) 


tJ 
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15: FOOBAR 8; 
FOOBAR being entered 
N: 8 
FOO being entered 
N8 
N := 
BAR being entered 
A1: 6 
FOO (level 2) being entered 
N: 2 


BAR (level 2) being entered 
Al: 0 
FOO (level 3) being entered 
N: 0 
FOO (level 3) = BOTTOM 
BAR (level 2) = BOTTOM 
A := BOTTOM 
N :3= -2 
BAR (level 2) being entered 
Als -2 
FOO (level 3) being entered 
N: 0 
FOO (level 3) = BOTTOM 
BAR (level 2) = BOTTOM 
FOO (level 2) = (BOTTOM BOTTOM BOTTOM) 
BAR = (BOTTOM BOTTOM BOTTOM) 
:= (BOTTOM BOTTOM BOTTOM) 
c= 4 
BAR being entered 
Al: 4 
FOO (level 2) being entered 
N: 2 
N := 0 
BAR (level 2) being entered 
Al: 0 
FOO (level 3) being entered 
N: 0 
FOO (level 3) = BOTTOM 
BAR (level 2) = BOTTOM 
:= BOTTOM 
22 =2 
BAR (level 2) being entered 
Als -2 
FOO (level 3) being entered 
N: 0 
FOO (level 3) = BOTTOM 
BAR (level 2) = BOTTOM 
FOO (level 2) = (BOTTOM BOTTOM BOTTOM) 
BAR = (BOTTOM BOTTOM BOTTOM) 
FOO = (%L1: (BOTTOM BOTTOM BOTTOM) (BOTTOM BOTTOM BOTTOM) 
2L1) 


Debugging Tools 
page 16.21 


Debugging Tools 22 July 1982 PSL Manual 
page 16.22 section 16.12 


FOOBAR = NIL 
0 

16: OFF TRACE; 
17: FOOBAR 8; 
0 


18: TR; 
*%** Start of saved trace information *** 
BAR (level 2) = BOTTOM 
FOO (level 2) = (BOTTOM BOTTOM BOTTOM) 
BAR = (BOTTOM BOTTOM BOTTOM) 
FOO = (L1: (BOTTOM BOTTOM BOTTOM) (BOTTOM BOTTOM BOTTOM) 
2L1) 
FOOBAR = NIL 
*** End of saved trace information **%* 


19: FOOBAR 13; 


*4%%* -1 illegal CAR 
20: TR; : 
#4#% Start of saved trace information *** 
BAR being entered 
Als 11 
FOO (level 2) being entered 
N: 3 
N := 1 
BAR (level 2) being entered 
Al: 1 
FOO (level 3) being entered 
N: -1 
*** End of saved trace information *** 


21: BTR; 

### Backtrace: *** 

These functions were left abnormally: 
FOO 


Als 11 
FOO 

N: 13 
FOOBAR 

N: 13 


J 
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2#% 


22: 
22: 
22: 
22: 
22: 
22: 


FOO = (4L1: 


End of backtrace **% 


SYMBOLIC EMB PROCEDURE FOO N; 

IF N < 0 THEN << 
LPRIM "FOO would have failed"; 
NIL >> 

ELSE 
FOO N; 


: RESBTR; 


FOOBAR 13; 

FOO WOULD HAVE FAILED 
FOO WOULD HAVE FAILED 
FOO WOULD HAVE FAILED 


FOO WOULD HAVE FAILED 


TR; 
Start of saved trace information **%* 
BAR (level 2) = NIL 
FOO (level 2) = (NIL NIL NIL) 
BAR = (NIL NIL NIL) 


FOOBAR = NIL 


HHH 


End of saved trace information *** 


26: BTR; 


** No traced functions were left abnormally *** 


27: UNEMBED FOO; 


(FOO) 


28: FOOBAR 13; 


#2*#4% 1 illegal CAR 


29: STUB FOO N; 


#*#% FOO REDEFINED 


30: FOOBAR 13; 
Stub FOO called 


(NIL NIL NIL) (NIL NIL NIL) £L1) 
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N: 13 

Return? : 

30: BAR(N-2); 
Stub FOO called 


N: 3 

Return? : 

30: BAR(N-2); 
Stub FOO called 


N: -1 
Return? : 
30: 'ERROR; 


0 
31: TR; 


*ž#ž## Start of saved trace information %*** 
BAR being entered 


Als 11 
BAR (level 2) being entered 
Als 1 
BAR (level 2) = ERROR 
BAR = ERROR 
FOOBAR = NIL 


*** End of saved trace information *** 


32: OFF TRCOUNT; 


FOOBAR(8) FeETESEELEL LES SF | 
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BAR( 24) FES PELL FE ETE EE EEE TEL EP EE ETS PTT TET ET TET ET ES FF 


33: QUIT; 


L 


L 


$ 
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CHAPTER 17 
EDITORS 

17.1. A Mini-Structure Editor 17.1 
17.2. The EMODE Screen Editor 17.3 

17.2.1. Windows and Buffers in Emode 17.5 
17.3. Introduction to the Full Structure Editor 17.6 
17.4. User Entry to Editor 17.6 
17.5. Editor Command Reference 17.8 


17.1. A Mini-Structure Editor 


PSL and RLISP provide a fairly simple structure editor, essentially a 
subset of the full editor below. This editor is usually resident in PSL 
and RLISP, or can be LOADed. It is useful for correcting errors in input, 
often via the E option in the BREAK loop. Do HELP(EDITOR) for more 
information. 


To edit an expression, call the function Edit with the expression as an 
argument. The edited copy is returned. To edit the definition of a 
function, call EditF with the function name as an argument. 


In the editor, the following commands are available (n indicates a 
non-negative integer): 


P edit 
Prints the subexpression under consideration. On entry, this is 
the entire expression. This only prints down PLEVEL levels, 
replacing all edited subexpressions by ***, PLEVEL is initially 
3. 

PL (N) edit 


Changes PLEVEL to N. 


N:integer edit-command 


Sets the subexpression under consideration to be the nth 
subexpression of the current one. That is, walk down to the nth 
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subexpression. 


~Nsinteger edit-command 


Sets the current subexpression to be the nth Cdr of the current 
one. 


UP edit 
Go to the subexpression you were in just before this one. 

T edit 
Go to the top of the original expression. 

F (5) edit 
Find the first occurrence of the S-expression S. The test is 
performed by Equal, not Eq. The current level is set to the 
first level in which S was found. 

(N:integer) - edit-command 
Delete the Nth element of the current expression. 

(Nsinteger [ARG]) edit-command 
Replace the Nth element by ARGs. 

(-N:integer [ARG]) edit-command 
Insert the elements ARGs before the nth element. 

(R S1 S2) edit 


Replace all occurrences of S1 (in the tree you are placed at) by 
S2. 


J 


J 
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B edit 


Enter a Break loop under the editor. 


OK edit 


Leave the editor, returning the edited expression. 


HELP edit 
Print an explanatory message. 


If the editor is called from a Break loop, the edited value is assigned 
back to ERRORFORM! *. 


17-2. The EMODE Screen Editor 


EMODE is an EMACS-like screen editor, written entirely in PSL. To invoke 
EMODE, call the function EMODE after LOADing the EMODE module. EMODE is 
modeled after EMACS, so use that fact as a guide. 


PSL:RLISP 
[1] LOAD EMODE; 
[2] EMODE(); 


<Ctrl-X Ctrl-2Z> 


"quits" to the EXEC (you can continue or start again). 
<Ctr1-Z Ctrl-Z> 
goes back into "normal" RLISP mode. 


EMODE is built to run on a Teleray terminal as the default. To use some 
other terminal you must LOAD in a set of different driver functions after 
loading EMODE. The following drivers are currently available: 


HP2648A 

TELERAY 

- VT100 

- VT52 

- AAA [Ann Arbor Ambassador] 


The sources for these files are on <PSL.EMODE> (logical name PE:). It 
should be quite easy to modify one of these files for other terminals. See 
the file PE:TERMINAL-DRIVERS.TXT for some more information on how this 
works. 
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An important (but currently somewhat bug-ridden) feature of EMODE is the 
ability to evaluate expressions that are in your buffer. Use <Meta-E> to 


evaluate 


the expression starting on the current line. <Meta-E> (normally) 


automatically enters two window mode if anything is "printed" to the 


OUT WINDOW buffer, 


which is shown in the lower window. If you don't want 


to see things being printed to the output window, you can set the variable 


!*#QUTWINDOW to 


NIL. (Or use the RLISP command "OFF QUTWINDOW;".) This 


prevents EMODE from automatically going into two window mode if something 
is printed to OUT WINDOW. You must still use the "<Ctrl-X> 1" command to 
enter one window mode initially. 


You may also find the <Ctrl-Meta~Y> command useful. This inserts into 
the current buffer the text printed as a result of the last <Meta-E>. 


The function 


"PrintAlldDispatch" prints out the current dispatch table. 


You must call EMODE before this table is set up. 


While in EMODE, the <Meta-?> (meta-question mark) character asks for a 
command character and tries to print information about it. 


The basic dispatch table is (roughly) as follows: 


Character 


<Ctr1-@> 
<Ctrl-A> 
<Ctrl-B> 
<Ctrl-D> 
<Ctrl-E> 
<Ctrl-F> 
Linefeed 
<Ctrl-K> 
<Ctrl-L> 
Return 

<Ctrl-N> 
<Ctr1-0> 
<Ctrl-P> 
<Ctrl-R> 


<Ctrl-S> 
<Ctr1-U> 


<Ctrl-V> 
<Ctrl-wW> 


Function i Comments 


SETMARK 

! $BEG INNINGOFLINE 

! $BACKWARDCHARACTER 

! $DELETEFORWARDCHARACTER 

! $ENDOFLINE 

! $FORWARDCHARACTER 

!$CRLF Acts like carriage return 

KILL_LINE 

FULLREFRESH 

!$CRLF 

! $FORWARDLINE 

OPENLINE 

! $BACKWARDLINE 
Backward search for string, type 
a carriage return to terminate 
the string 
Forward search for string 
Repeat a command. Asks for 
count (terminate with a carriage 
return), then it asks for the 
command character 

DOWNW INDOW 

KILL REGION 
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<Ctrl1-X> 


<Ctri-Y> 
<Ctrl-2> 


escape 


rubout 


<Ctrl-Meta-B> 
<Ctrl-Meta-F> 
<Ctrl-Meta-K> 
<Ctrl-Meta-Y> 


<Ctrl-Meta-Z> 


<Meta-Ctrl-rubout> 


<Meta-<> 


<Meta->> 


<Meta-?> 


<Meta-B> 
<Meta-D> 
<Meta-E> 
<Meta-V> 
<Meta-W> 
<Meta-X> 


<Meta-Y> 


<Meta=Rubout> 


<Ctrl-X> 
<Ctrl-X> 
<Ctrl-X> 
<Ctrl-X> 
<Ctrl-X> 
<Ctrl-X> 
<Ctrl-X> 
<Ctrl-X> 


<Ctrl-X> 
<Ctrl-X> 


<Ctrl-B> 
<Ctrl-R> 
<Ctrl-W> 
<Ctrl-X> 
<Ctrl-Z> 
7 
2 
B 


O 
P 
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! $DOCNTRLX 


INSERT_KILL_BUFFER 
DOCONTROLMETA. 


ESCAPEASMETA 
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As in EMACS, <Ctrl-X> is a 
prefix for "fancier" commands 
Yanks back killed text 

As in EMACS, acts like 
<Ctrl-Meta-> 

As in EMACS, escape acts like 
the <Meta-> key 


! $D ELETEBACKWARDCHARACTER 


BACKWARD SEXPR 
FORWARD_SEXPR 
KILL_ FORWARD _SEXPR 


INSERT LAST EXPRESSION Insert the last "expression" 


OLDFACE 


KILL BACKWARD _SEXPR 
! $BEGINNINGOF BUFFER 


! $ENDOF BUFFER 
! $HELPDISPATCH 


BACKWARD_WORD 
KILL FORWARD WORD 


UPWINDOW 
COPY_REGION 
! $DOMETAX 


UNKILL PREVIOUS 
KILL BACKWARD WORD 
PRINTBUFFERNAMES 
CNTRLXREAD 
CNTRLXWRITE 


EXCHANGEPOINTANDMARK 


ONEW INDOW 
TWOWINDOWS 
CHOOSEBUFFER 


OTHERW INDOW 
WRITESCREEN PHOTO 


17.2.1. Windows and Buffers in Emode 


typed as the result of a 
<Meta-E> 

Leave EMODE, go back to 
"regular" RLISP 


As in EMACS, move to beginning 
of buffer 

As in EMACS, move to end of 
buffer 

Asks for a character, tries to 
print information about it 


Evaluate an expression 
As in EMACS, move up a window 


As in EMACS, <Meta-X> is another 
prefix for "fancy" stuff 
As in EMACS 


Prints a list of buffers 
Read a file into the buffer 
Write the buffer out to a file 


As in EMACS, exits to the EXEC 
Go into one window mode 

Go into two window mode 

EMODE asks for a buffer name, 
and then puts you in that buffer 
Select other window 

Write a "photograph" of the 
screen to a file 


- Global Variable “WINDOWNAMES' is list of (windows.info) 


- CreateWindow(Wname , Bname ,Coord(Left,Top) ,Coord( Right, Bottom) ) 
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[Left,Right:1..18, Top,Bottom:1..70] 


- SelectWindow(Wname); DeselectWindow(Wname); KillWindow(Wname) ; 


17.3. Introduction to the Full Structure Editor 


1 

PSL also provides an extremely powerful form-oriented editor . This 
facility allows the user to easily alter function definitions, variable 
values and property list entries. It thereby makes it entirely unnecessary 
for the user to employ a conventional text editor in the maintenance of 
programs. This document is a guide to using the editor. Certain features 
of the UCI LISP editor have not been incorporated in the translated editor, 
and we have tried to mark all such differences. 


17.4. User Entry to Editor 

This Section describes normal user entry to the editor (EditF, EditP and 
EditV) and the editing commands which are available. This Section is by no 
means complete. In particular, material covering programmed calls to the 


“editor routines is not treated. Consult the UCI LISP manual for further 
details. 


To edit a function named FOO do 
*(EDITF FOO) 
To edit the value of an atom named BAZ do 
*(EDITV BAZ) 
To edit the property list of an atom named FOOBAZ do 


* 


*(EDITP FOOBAZ) 


1 

This version of the UCI LISP editor was translated to to Standard LISP 
by Tryg Ager and Jim MacDonald of IMSSS, Stanford, and adapted to PSL by 
E. Benson. The UCI LISP editor is derived from the INTER LISP editor. 
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These functions are described later in the Chapter. 


Warning: Editing the property list of an atom may position pointers at 
unprintable structures. It is best to use the F (find) command before 
trying to print property lists. This editor capability is variable from 
implementation to implementation. 


The Editor prompts with 
ake 
* 


You can then input any editor command. The input scanner is not very 


smart. lt terminates its scan and begins processing when it sees a 
printable character immediately followed by a carriage return. Do not use 
escape to terminate an editor command. If the editor seems to be 


repeatedly requesting input type P<ret> (print the current expression) or 
some other command that ordinarily does no damage, but terminates the input 
solicitation. 


The following set of topics makes a good 'first glance' at the editor. 


Entering the editor: EDITF, EDITV. 

Leaving the editor: OK. 

Editor's attention: CURRENT-EXP. 

Changing attention: POS-INTEGER, NEG-INTEGER, 0, “, NX, BK. 


Printing: P, PP. 

Modification: POS-INTEGER, NEG-INTEGER, A, B, :, N. 
Changing parens: BI, BO. 

Undoing changes: UNDO. 


For the more discriminating user, the next topics might be some of the 
following. 


Searches: PATTERN, F, BF. 
Complex commands: R, SW, XTR, MBD, MOVE. 
Changing parens: LI, LO, RI, RO. 
Undoing changes: TEST, UNBLOCK, !UNDO. 


Other features should be skimmed but not studied until it appears that 
they may be useful. 
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17.5. Editor Command Reference 


Note that arguments contained in angle brackets <> are optional. 


A ([ARG]) edit 


This command inserts the ARGs (arbitrary LISP expressions) After 
the current expression. This is accomplished by doing an UP and 
a (-2 expl exp2 +... expn) or an (N expl exp2 ... expn), as 
appropriate. Note the way in which the current expression is 
changed by the UP. 


B ([ARG]) edit 


This command inserts the ARGs (arbitrary LISP forms) Before the 
current expression. This is accomplished by doing an UP followed 
by a (-1 exp] exp2 ... expn). Note the way in which the current 
expression is changed by the UP. 


BELOW (COM, <N>) E edit 


This command changes the .current expression in the following 
manner. The edit command COM is executed. If COM is not a 
recognized command, then (_ COM) is executed instead. Note that 
COM should cause ascent in the edit chain (i.e. should be 
equivalent to some number of zeros). BELOW then evaluates 
(note!) N and descends N links in the resulting edit chain. That 
is, BELOW ascends the edit chain (does repeated 0s) looking for 
the link specified by COM and stops N-links below that (backs off 
N Os). If N is not given, 1 is assumed. 


BF (PAT, <FLG>) edit 


Also can be used as: 
BF PAT 


This command performs a Backwards Find, searching for PAT (an 
edit pattern). Search begins with the expression immediately 
before the current expression and proceeds in reverse print 
order. (If the current expression is the top level expression, 
the entire expression is searched in reverse print order.) 
Search begins at the end of each list, and descends into each 
element before attempting to match that element. If the match 
fails, proceed to the previous element, etc. until the front of 
the list is reached. At that point, BF ascends and backs up, 
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The search algorithm may.be slightly modified by use of a second 
argument. Possible FLGs and their meanings are as follows. 


T begins search with the current expression rather than 
with the preceding expression at this level. 
NIL or missing ~ same as BF PAT. 


NOTE: if the variable UPFINDFLG is non-NIL, the editor does an 
UP after the expression matching PAT is located. Thus, doing a 
BF for a function name yields a current expression which is the 
entire function call. If this is not desired, UPFINDFLG may be 
set to NIL. UPFINDFLG is initially T. 


BF is protected from circular searches by the variable MAXLEVEL. 
If the total number of Cars and Cdrs descended into reaches 
MAXLEVEL (initially 300), search of that tail or element is 
abandoned exactly as though a complete search had failed. 


BI (N1, N2) 


BIND 


This command inserts a pair of parentheses in the current 
expression; i.e. it is a Balanced Insert. (Note that parentheses 
are ALWAYS balanced, and hence must be added or removed in 
pairs.) A left paren is inserted before element N1 of the 
current expression. A right paren is inserted after element N2 
of the current expression. Both N1 and N2 are usually integers, 
and element N2 must be to the right of element N1. 


(BI n1) is equivalent to (BI n1 n1). 


The NTH command is used in the search, so that N1 and N2 may be 
any location specifications. The expressions used are the first 
element of the current expression in which the specified form is 
found at any level. 


(Lcom]) 


This command provides the user with temporary variables for use 
during the execution of the sequence of edit commands coms. 
There are three variables available: #1, #2 and #3. The binding 
is recursive and BIND may be executed recursively if necessary. 
All variables are initialized to NIL. This feature is useful 


edit 


edit 
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cniefiy in defining edit macros. 


BK edit 


The current expression becomes the expression immediately 
preceding the present current expression; i.e. Back Up. This 
command generates an error if the current expression is the first 
expression in the list. 


BO (N) edit 


The BO command removes a pair of parentheses from the Nth element 
of the current expression; i.e. it is a Balanced Remove. The 
parameter N is usually an integer. The NTH command is used in 
the search, however, so that any location specification may be 
used. The expression referred to is the first element of the 
current expression in which the specified form is found at any 
level. 


(CHANGE LOC To [ARG]) edit 


This command replaces the current expression after executing the 
leeation specification LOC by ARGS. 


(COMS [ARG]) edit 
This command evaluates its ARGs and executes them as edit 
commands. 

(COMSQ [ ARG]) l edit 


This command executes each ARG as an edit command. 


At any given time, the attention of the editor is focused on a single 
expression or form. We call that form the current expression., Editor 
commands may be divided into two broad classes. Those commands which 
change the current expression are called attention- changing commands. 
Those commands which modify structure are called structure modification 
commands. 


DELETE edit 
This command deletes the current expression. If the current 


expression is a tail, only the first element is deleted. This 
command is equivalent to (:). 


E 


J 
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(E FORM <T>) A edit 


This command evaluates FORM. This may also be typed in as: 


E FORM 


but is valid only if typed in from the TTY. (E FORM) evaluates 
FORM and prints the value on the terminal. The form (E FORM T) 
evaluates FORM but does not print the result. 


EditF (FN:id, COMS:forms): any expr 
This function initiates editing of the function whose name is FN. 


The argument COMS is a possibly null sequence of edit commands 
which is executed before calling for input from the terminal. 


EditFns (FN-LIST:id-list, COMS:form): NIL fexpr 
This function applies the sequence of editor commands, COMS, to 
each of several functions. The argument FN-LIST is evaluated, 
and should evaluate to a list of function names. COMS is applied 
to each function in FN-LIST, in turn. Errors in editing one 
function do not affect editing of others. The editor call is via 
EditF, so that values may also be edited in this way. 


EditP (AT:id, COMS:form-list): any fexpr 


This function initiates editing of the property list of the atom 
whose name is at. The argument COMS is a possibly null sequence 
of edit commands which is executed before calling for input from 
the terminal. 


EditV (AT:id, COMS:forms-list): NIL fexpr 
This function initiates editing of the value of the atom whose 
name is AT. The argument COMS is a possibly null sequence of 
edit commands which is executed before calling for input from the 
terminal. 

(EMBED LOC In ARG) edit 


This command replaces the expression which would be current after 
executing the location specification LOC by another expression 
which has that expression as a sub-expression. The manner in 
which the transformation is carried out depends on the form of 
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ARG. If ARG is a list, then each occurrence of the atom '*! in 
ARG is replaced by the expression which would be current after 


doing LOC. (NOTE: a fresh copy is used for each substitution.) 
If. ARG is atomic, the result is equivalent to: 


(EMBED loc IN (arg *)) 

A call of the form 

(EMBED loc IN exp! exp2 +... expn) 

is equivalent to: 

(EMBED loc IN (exp1 exp2 +... expn *)) 


If the expression after doing LOC is a tail, EMBED behaves as 
though the expression were the first element of that tail. 


(EXTRACT LOC1 From LOC2) E © edit 


This command replaces the expression which would be current after 
doing the location specification LOC2 by the expression which 
would be current after doing LOC1. The expression specified by 
LOC1 must be a sub-expression of that specified by LOC2. 


(F PAT <FLG>) edit 


Also can be used as: 
F PAT 


This command causes the next command, PAT, to be interpreted as a 
pattern. The current expression is searched for the next 
occurrence of PAT; i.e. Find. If PAT is a top level element of 
the current expression, then PAT matches that top level 
occurrence and a full recursive search is not attempted. 
Otherwise, the search proceeds in print order. Recursion is done 
first in the Car and then in the Cdr direction. 


The form (F PAT FLG) of the command may be used to modify the 
search algorithm according to the value of FLG. Possible values 


4 


C 
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and their actions are: 


N suppresses the top-level check. That is, finds the 
next print order occurrence of PAT regardless of any 
top level occurrences. 


T like N, but may succeed witnout changing the current 
expression. That is, succeeds even if the current 
expression itself is the only occurrence of PAT. 


positive integer 
finds the nth place at which PAT is matched. This is 
equivalent to (F PAT T) followed by n-1 (F PAT N)s. If 
n occurrences are not found, the current expression is 
unchanged. 


NIL or missing 
Only searches top level elements of the current 
expression. May succeed without changing the current 
expression. 


NOTE: If the variable UPFINDFLG is non-NIL, F does an UP after 
locating a match. This ensures that F fn, in which fn is a 
function name, results in a current expression which is the 
entire function call. If this is undesirable, set UPFINDFLG to 
NIL. Its initial value is T. 


As protection against searching circular lists, the search is 
abandoned if the total number of Car-Cdr descents exceeds the 
value of the variable MAXLEVEL. (The initial value is 300.) The 
search fails just as if the entire element had been 
unsuccessfully searched. 


(FS [PAT]) | edit 


The FS command does sequential finds; i.e. Find Sequential. That 
is, it searches (in print order) first for the first PAT, then 
for the second PAT, etc. If any search fails, the current 
expression is left at that form which matched in the last 
successful search. This command is, therefore, equivalent to a 
sequence of F commands. 
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(F= EXP FLG) 
This command is equivalent to (F (== exp) flg); i.e. Find Eq. 
That is, it searches, in the manner specified by FLG, for a form 
which is Eq to EXP. Note that for keyboard type-ins, this always 
fails unless EXP is atomic. 

HELP 


This command provides an easy way of invoking the HELP system 
from the editor. 


(I COM [ARG]) 


This command evaluates the ARGs and executes COM on the resulting 
values. This command is thus equivalent to: (com vali val2 ... 
valn), Each vali is equal to (EVAL argi). 


(IF ARG) 


This command, useful in edit macros, conditionally causes an 
editor error. If (EVAL arg) is NIL (or if evaluation of arg 
causes a LISP error), then IF generates an editor error. 


(INSERT [EXP ARG LOC]) 


The INSERT command provides equivalents of the A, Band : 
commands incorporating a location specification, LOC. ARG can be 
AFTER, BEFORE, or FOR. This command inserts EXPs AFTER, BEFORE 
or FOR (in place of) the expression which is current after 
executing LOC. Note, however, that the current expression is not 
changed. 


(LC LOC) 


This command, which takes as an argument a location 
specification, explicitly invokes the location specification 
search; i.e. Locate. The current expression is changed to that 
which is current after executing LOC. 


See LOC-SPEC for details on the definition of LOC and the search 
method in question. 


17.5 


edit 


edit 


edit 


edit 


edit 


edit 
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(LCL LOC) edit 


This command, which takes as an argument a location 
specification, explicitly invokes the location specification 
search. However, the search is limited to the current expression 
itself; i.e. Locate Limited. The current expression is changed 
to that which is current after executing LOC. 


(LI N) edit 


This command inserts a left parenthesis (and, of course, a 
matching right paren); i.e. Left Paren Insert. The left paren is 
inserted before the Nth element of the current expression and the 
right paren at the end of the current expression. Thus, this 
command is equivalent to (BI n <1). 


The NTH command is used in the search, so that N, which is 
usually an integer, may be any location specification. The 
expression referred to is the first element of the current 
expression which contains the form specified at any level. 


(LO N) | edit 


This command removes a left parenthesis (and a matching right 
paren, of course) from the Nth element of the current expression; 
i.e. Left Paren Remove. All elements after the Nth are deleted. 


The command uses the NTH command for the search. The parameter 
N, which is usually an integer, may be any location 
specification. The expression actually referred to is the first 
element of the current expression which contains the specified 
form at any depth. 


Many of the more complex edit commands take as an argument a location 
specification (abbreviated LOC throughout this document). A location 
specification is a list of edit commands, which are, with two exceptions, 
executed in the normal way. Any command not recognized by the editor is 
treated as though it were preceded by F. Furthermore, if one of the 
commands causes an error and the current expression has been changed by 
prior commands, the location operation continues rather than aborting. 
This is a sort of back-up operation. For example, suppose the location 
specification is (COND 2 3), and the first clause of the first Cond has 
only 2 forms. The location operation proceeds by searching for the next 
Cond and trying again. If a point were reached in which there were no more 
Conds, the location operation would then fail. 
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(LP COMS) edit 


This command, useful in macros, repeatedly executes COMS (a 
sequence of edit commands) until an editor error occurs; i.e. 
Loop. As LP exits, it prints the number of OCCURRENCES; that is, 
the number of times COMS was successfully executed. After 
execution of the command, the current expression is left at what 
it was after the last complete successful execution of COMS. 


The command terminates if the number of iterations exceeds the 
value of the variable MAXLOOP (initially 30). 


(LPQ COMS) edit 
This command, useful in macros, repeatedly executes COMS (a 
sequence of edit commands) until an editor error occurs; i.e. 

Loop Quietly. After execution of the command, the current 


expression is left at what it was after the last complete 
successful execution of COMS. 


The command terminates if the number of iterations exceeds the 
value of the variable MAXLOOP (initially 30). 


This command is equivalent to LP, except that OCCURRENCES is not 
printed. i 


(M (NAM) ([EXP) COMS)]) edit 


This can also be used as: 
(M NAM COMS) 

or as: 

(M (NAM) ARG COMS) 


The editor provides the user with a macro facility; i.e. M. The 
user may define frequently used command sequences to be edit 
macros, which may then be invoked simply by giving the macro name 
as an edit command. The M command provides the user with a 
method of defining edit macros. 
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The first alternate form of the command defines an atomic command 
which takes no arguments. The argument NAM is the atomic name of 
the macro. This defines NAM to be an edit macro equivalent to 
the sequence of edit commands COMS. If NAM previously had a 
definition as an edit macro, the new definition replaces the old. 
NOTE: Edit command names take precedence over macros. It is not 
possible to redefine edit command names. 


The main form of the M command as given above defines a list 
command, which takes a fixed number of arguments. In this case, 
NAM is defined to be an edit macro equivalent to the sequence of 
edit commands COMS. However, as (nam expl exp2 +... expn) is 
executed, the expi are substituted for the corresponding argi in 
COMS before COMS are executed. 


The second alternate form of the M command defines a list command 
which may take an arbitrary number of arguments. Execution of 
the macro NAM is accomplished by substituting (exp1 exp2 ... 
expn) (that is, the Cdr of the macro call. (mam expl exp2 +... 
expn)) for all occurrences of the atom ARG in COMS, and then 
executing COMS. 


$ 


(MAKEFN (NAM VARS) ARGS N1 <N2>) 


MARK 


This command defines a portion of the current expression as a 
function and replaces that portion of the expression by a call to 
the function; i.e. Make Function. The form (NAM VARS) is the 
call which replaces the Nist through N2nd elements of the current 
expression. Thus, NAM is the name of the function to be defined. 
VARS is a sequence of local variables (in the current 
expression), and ARGS is a list of dummy variables. The function 
definition is formed by replacing each occurrence of an element 
in vars (the Cdr of (NAM VARS)) by the corresponding element of 
ARGS. Thus, ARGS are the names of the formal parameters in the 
newly defined function. 


If N2 is omitted, it is assumed to be equal to N1. 


This command saves the current position within the form in such a 
way that it can later be returned to. The return is accomplished 
via or . 


page 17.17 


edit 


edit 
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MBD (ARG) edit 


This command replaces the current expression by some form which 
nas the current expression as a sub-expression. If ARG is a 
list, MBD substitutes a fresh copy of the current expression for 
each occurrence of the atom '*' in ARG. If ARG is a sequence of 
expressions, as: 


(MBD exp1 exp2 ... expn) 

then the call is equivalent to one of the form: 
(MBD (exp1 exp2 ... expn *)) 

The same is true if arg is atomic: 

(MBD atom) = (MBD (atom *)) 


(MOVE <LOC1> To COM <LOC2>) edit 


The MOVE command allows the user to Move a structure from one 
point to another. The user may specify the form to be moved (via 
LOC1, the first location specification), the position to which it 
is to be moved (via LOC2, the second location specification) and 
the action to be performed there (via COM). The argument COM may 
be BEFORE, AFTER or the name of a list command (e.g. :, N, etc.). 
This command performs in the following manner. Take the current 
expression after executing LOC1 (or its first element, if it is a 
tail); call it expr. Execute LOC2 (beginning at the current 
expression AS OF ENTRY TO MOVE -- NOT the expression which would 
be current after execution of LOC1), and then execute (COM expr). 
Now go back and delete expr from its original position. The 
current expression is not changed by this command. 


If LOCi is NIL (that is, missing), the current expression is 
moved. In this case, the current expression becomes the result 
of the execution of (COM expr). 


If LOC2 is NIL (that is missing) or HERE, then the current 
expression specifies the point to which the form given by LOC2 is 
to be moved. 


aJ 
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(N [EXP]) | edit 


This command adds the EXPs to the end of the current expression; 
i.e. Add at End. This compensates for the fact that the negative 
integer command does not allow insertion after the last element. 


(-Nsinteger [EXP]) edit-command 
Also can be used as: 
-N 


This is really two separate commands. The atomic form is an 
attention changing command. The current expression becomes the 
nth form from the end of the old current expression; i.e. Add 
Before End. That is, -1 specifies the last element, -2 the 
second from last, etc. 


The list form of the command is a structure modification command. 
This command inserts exp1 through expn (at least one expi must be 
present) before the nth element (counting from the BEGINNING) of 
the current expression. That is, -1 inserts before the first 
element, -2 before the second, etc. 


(NEX COM) edit 


Also can be used as: 
NEX 


This command is equivalent to (BELOW COM) followed by NX. That 
is, it does repeated Os until a current expression matching com 
is found. It then backs off by one 0 and does a NX. 


The atomic form of the command is equivalent to (NEX _). This is 
useful if the user is doing repeated (NEX x)s. He can MARK at x 
and then use the atomic form. 


(NTH LOC) edit 


This command effectively performs (LCL LOC), (BELOW <), UP. The 
net effect is to search the current expression only for the form 
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specified by the location specification LOC. From there, return 
to the initial level and set the current expression to be the 
tail whose first element contains the form specified by LOC at 
any level. 


(NX N) 


OK 


(ORF 


Also can be used as: 
NX 


The atomic form of this command makes the current expression the 
expression following the present current expression (at the same 
level); i.e. Next. 


The list form of the command is equivalent to n (an integer 
number) repetitions of NX. If an error occurs (e.g. if there are 
not N expressions following the current expression), the current 
expression is unchanged. 


This command causes normal exit from the editor. 


The state of the edit is saved on property LASTVALUE of the atom 
EDIT. If the next form edited is the same, the edit is restored. 
That is, it is (with the exception of a BLOCK on the undo-list) 
as though the editor had never been exited. 


It is possible to save edit states for more than one form by 
exiting from the editor via the SAVE command. 


(PAT]) 


This command searches the current expression, in print order, for 
the first occurrence of any form which matches one of the PATs; 
i.e. Print Order Final. If found, an UP is executed, and the 
current expression becomes the expression so specified. This 
command is equivalent to (F (*ANY* pat1 pat2 ... patn) N). Note 
that the top level check is not performed. 


17.5 


edit 


edit 


edit 
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(ORR [COMS]) edit 


This command operates in the following manner. Each COMS is a 
list of edit commands. ORR first executes the first COMS. If no 
error occurs, ORR terminates, leaving the current expression as 
it was at the end of executing COMS. Otherwise, it restores the 
current expression to what it was on entry and repeats this 
operation on the second COMS, etc. If no COMS is successfully 
executed without error, ORR generates an error and the current 
expression is unchanged. 


(P N1 <N2>) 


Also can be used as: 


This command prints the current expression; i.e. Print. The 
atomic form of the command prints the current expression to a 
depth of 2. More deeply nested forms are printed as &. 


The form (P Ni) prints the Nist element of the current expression 
to a depth of 2. The argument N1 need not be an integer. It may 
be a general location specification. The NTH command is used in 
the search, so that the expression printed is the first element 
of the current expression which contains the desired form at any 
level. 


The third form of the command prints the Nist element of the 
current expression to a depth of N2. Again, N1 may be a general 
location specification. 


If N1 is 0, the current expression is printed. 


Many of the editor commands, particularly those which search, 
take as an argument a pattern (abbreviated PAT). A pattern may 
be any combination of literal list structure and special pattern 
elements. 


The special elements are as follows. 


& this matches any single element. 


edit 
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* ANY # if (CAR pat) is the atom *ANY#, then (CDR pat) must be 
a list of patterns. PAT matches any form which matches 
any of the patterns in (Cdr PAT). 


a if an element of pat is a literal atom whose last 
character is @, then that element matches any literal 
atom whose initial characters match the initial 
characters of the element. That is, VER matches 
VERYLONGATOM. 


-- this matches any tail of a list or any interior segment 
of a list. 


== if (Car PAT) is ==, then PAT matches X iff (Cdr PAT) is 
Eq to X. 


aie if PAT begins with :::, the Cdr of PAT is matched 
against tails of the expression. 


(Nsinteger [EXP]) l edit-command 
Also can be used as: 
Nsinteger 


This command, a strictly positive integer N, is really two 
commands. The atomic form of the command is an 
attention-changing command. The current expression becomes the 
nth element of the current expression. 


The list form of the command is a structure modification command. 
It replaces the Nth element of the current expression by the 
forms EXP. If no forms are given, then the Nth element of the 
current expression is deleted. 


PP edit 


This command Pretty-Prints the current expression. 
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(R EXP1 EXP2) edit 


This command Replaces all occurrences of EXP1 by EXP2 in the 
current expression. 


Note that EXP1 may be either the literal s-expression to be 
replaced, or it may be an edit pattern. If a pattern is given, 
the Form which first matches that pattern is replaced throughout. 
All forms which match the pattern are NOT replaced. 


(REPACK LOC) edit 


Also can be used as: 
REPACK 


This command allows the editing of long strings lor atom names) 
one character at a time. REPACK calls the editor recursively on 
UNPACK of the specified atom. (In the atomic form of the 
command, the current expression is used unless it is a list; 
then, the first element is used. In the list form of the 
command, the form specified by the location specification is 
treated in the same way.) If the lower editor is exited via OK, 
the result is repacked and replaces the original atom. If STOP 
is used, no replacement is done. The new atom is always printed. 


(RI N1 N2) edit 


This command moves a right parenthesis. The paren is moved from 
the end of the the Nist element of the current expression to 
after the N2nd element of the Nist element; i.e. Right Paren 
Insert. Remaining elements of the Nist element are raised to the 
top level of the current expression. 


The arguments, Ni and N2, are normally integers. However, 
because the NTH command is used in the search, they may be any 
location specifications. The expressions referred to are the 
first element of the current expression in which the specified 
form is found at any level, and the first element of that 
expression in which the form specified by N2 is found at any 
level. 
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(RO N) 
This command moves the right parenthesis from the end of the nth 
element. of the current expression to the end of the current 
expression; i.e. Right Paren Remove. All elements following the 
Nth are moved inside the nth element. 
Because the NTH command is used for the search, the argument N, 
which is normally an integer, may be any location specification. 
The expression referred to is the first element of the current 
expression in which the specified form is found at any depth. 

(S VAR LOC) 
This command Sets (via SetQ) the variable whose name is VAR to 
the current expression after executing the location specification 
LOC. The current expression is not changed. 

SAVE 


This command exits normally from the editor. The state of the 
edit is saved on the property EDIT-SAVE of the atom being edited. 
When the same atom is next edited, the state of the edit is 
restored and (with the exception of a BLOCK on the undo-list) it 
is as if the editor had never been exited. It.is not necessary 
to use the SAVE command if only a single atom is being edited. 
See the OK command. 


(SECOND LOC) 


STOP 


This command changes the current expression to what it would be 
after the location specification LOC is executed twice. The 
current expression is unchanged if either execution of LOC fails. 


This command exits abnormally from the editor; i.e. Stop Editing. 
This command is useful mainly in conjunction with TTY: commands 
which the user wishes to abort. For example, if the user is 
executing 


(MOVE 3 TO AFTER COND TTY:) 


and he exits from the lower editor via OK, the MOVE command 
completes its operation. If, on the other hand, the user exits 


17.5 


edit 


edit 


edit 


edit 


edit 
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via STOP, TTY: produces an error and MOVE aborts. 


(SN N1 N2) edit 


This command Swaps the Nist and N2nd elements of the current 
expression. The arguments are normally but not necessarily 
integers. SW uses NTH to perform the search, so that any 
location specifications may be used. In each case, the first 
element of the current expression which contains the specified 
Form at any depth is used. 


TEST edit 


This command adds an undo-block to the undo-list. This block 
limits the scope of UNDO and !UNDO commands to changes made after 
the block was inserted. The block may be removed via UNBLOCK. 


(THIRD LOC) , edit 


This command executes the location specification loc three times. 
It is equivalent to three repetitions of (LC LOC). Note, 
however, that if any of the executions causes an editor error, 
the current expression remains unchanged. 


(LOC1 THROUGH LOC2) edit 


This command makes the current expression the segment from the 
form specified by LOC1 through (including) the form specified by 
LOC2. It is equivalent to (LC LOC1), UP, (BI 1 LOC2), 1. Thus, 
it makes a single element of the specified elements and makes 
that the current expression. 


This command is meant for use in the location specifications 
given to the DELETE, EMBED, EXTRACT and REPLACE commands, and is 
not particularly useful by itself. Use of THROUGH with these 
commands sets a special flag so that the editor removes the extra 
set of parens added by THROUGH. 


(LOC1 TO LOC2) edit 


This command makes the current expression the segment from the 
form specified by LOC1 up to (but not including) the form 
specified by LOC2. It is equivalent to (LC LOC1), UP, (BI 1 
loc), (RI 1 -2), 1. Thus, it makes a single element of the 
specified elements and makes that the current expression. 
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This command is meant for use in the location specifications 
given to the DELETE, EMBED, EXTRACT and REPLACE commands, and is 
not particularly useful by itself. Use of TO with these commands 
sets a special flag so that the editor removes the extra set of 
parens added by TO. 


This command calls the editor recursively, invoking a ‘lower 
editor.' The user may execute any and all edit commands in this 
lower editor. The TTY: command terminates when the lower editor 
is exited via OK or STOP. 


The form being edited in the lower editor is the same as that 
being edited in the upper editor. Upon entry, the current 
expression in the lower is the same as that in the upper editor. 


UNBLOCK 


UNDO 


This command removes an undo-block from the undo-list, allowing 
UNDO and !UNDO to operate on changes which were made before the 
block was inserted. 


Blocks may be inserted by exiting from the editor and by the TEST 
command. 


(COM) 


Also can use as: 
UNDO 


This command undoes editing changes. All editing changes are 
undoable, provided that the information is available to the 
editor. (The necessary information is always available unless 
several forms are being edited and the SAVE command is not used.) 
Changes made in the current editing session are ALWAYS undoable. 


The short form of the command undoes the most recent change. 
Note, however, that UNDO and !UNDO changes are skipped, even 
though they are themselves undoable. 


The long form of the command allows the user to undo an arbitrary 


17.5 


edit 


edit 


edit 
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command, not necessarily the most recent» UNDO and ¿UNDO may 
also be undone in this manner. 


UP edit 


If the current expression is a tail of the next higher 
expression, UP has no effect. therwise the current expression 
becomes the form whose first element is the old current 
expression. 


(XTR LOC) edit 


This command replaces the current expression by one of its 
subexpressions. The location specification, LOC, gives the form 
to be used. Note that only the current expression is searched. 
If the current expression is a tail, the command operates on the 
first element of the tail. 


0 edit-command 


This command makes the current expression the next higher 
expression. This usually, but not always, corresponds to 
returning to the next higher left parenthesis. This command is, 
in some sense, the inverse of the POS-INTEGER and NEG- INTEGER 
atomic commands. 


HH ([COM:form]): any fexpr, edit-command 


The value of this fsubr, useful mainly in macros, is the 
expression which would be current after executing all of the COMs 
in sequence. The current expression is not changed. 


Commands in which this fsubr might be used (e.g. CHANGE, INSERT, and 
REPLACE) make special checks and use a copy of the expression returned. 


edit-command 


This command makes the top level expression the current 
expression. 


? edit-command 
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el 


This command prints the current expression to a level of 100. It 
is equivalent to (P 0 100). 


edit-command 


This command displays the entries on the undo-list. 


edit-command 


This command returns to the position indicated by the most recent 
MARK command. The MARK is not removed. 


(_ PAT) edit-command 


This command ascends (does repeated Os), testing the current 
expression at each ascent for a match with PAT. The current 
expression becomes the first form to match. If pattern is 
atomic, it is matched with the first element of each expression; 
otherwise, it is matched against the entire form. 


edit~command 


This command returns to the position indicated by the most recent 
MARK command and removes the MARK. 


(3; [EXP]) edit-command 


Also can be used as: 


(2) 


This command replaces the current expression by the forms EXP. 
If no forms are given (as in the second form of the command), the 
current expression is deleted: 


(PAT 23: LOC) edit-command 


This command sets the current expression to the first form (in 


cy 


om) 
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\P 


print order) which matches PAT and contains the form specified by 
the location specification LOC at any level. The command is 
equivalent to (F PAT N), (LCL LOC), (_ PAT). 


edit-command 


This command returns to the expression which was current before 
the last 'big jump.' Big jumps are caused by these commands: ^, 
_» __y !NX, all commands which perform a search or use a location 
specification, \ itself, and MAP. NOTE: \ is shift-L ona 
teletype. 


edit-command 


This command returns to the expression which was current before 
the last print operation (P, PP or ?). Only the two most recent 
locations are saved. NOTE: \ is shift-L on a teletype. 


edit-command 


This command makes the next expression at a higher level the 
current expression. That is, it goes through any number of right 
parentheses to get to the next expression. 


1UNDO edit-command 


This command undoes all changes made in the current editing 
session (back to the most recent block). All changes are 
undoable. 


Blocks may be inserted by exiting the editor or by the TEST 
command. They may be removed with the UNBLOCK command. 


edit-command 


This command does repeated Os until it reaches an expression 
which is not a tail of the next higher expression. That 
expression becomes the new current expression. That is, this 
command returns to the next higher left parenthesis, regardless 
of intervening tails. i 


wd 
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CHAPTER 18 
NEW UTILITIES 


18.1. Introduction 18.1 
18.2. RCREF — Cross Reference Generator for PSL Files 18.1 
18.2.1. Restrictions 18.2 
18.2.2. Usage 18.3 
18.2.3. Options 18.3 
18.3. Picture RLISP 18.3 


18.3.1. Running PictureRLISP on HP2648A and on TEKTRONIX 18.10 
4006-1 Terminals 


18.4. Tools for Defining Macros 18.10 
18.4.1. DefMacro 18.11 
18.4.2. BackQuote 18.11 
18.4.3. Sharp-Sign Macros 18.12 
18.4.4. MacroExpand 18.13 
18.4.5. DefLambda 18.13 

18.5. Simulating a Stack 18.13 

18.6. DefStruct 18. 14 
18.6.1. Options 18.16 
18.6.2. Slot Options 18.17 
18.6.3. A Simple Example 18.18 

18.7. DefConst 18.21 

18.8. Find 18.21 

18.9. Hashing Cons 18.22 

18.10. Graph-to-Tree 18.23 

18.11. Inspect Utility 18.24 

18.12. Trigonometric and Other Mathematical Functions 18.25 


18.1. Introduction 


This Chapter describes an assortment of utility packages that are too new 
either to be included elsewhere or to have a Chapter of their own. The 
main purpose is to record the existence and capabilities of a number of 
tools. More ¡information on existing packages can be found by looking at 
the current set of HELP files (DIR PH:*.* on the DEC-20). 


18.2. RCREF - Cross Reference Generator for PSL Files 


RCREF is a Standard LISP program for processing a set of Standard LISP 
function definitions to produce: 


a. A "Summary" showing: 
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It should also be remembered that in REDUCE (RLISP) any macros with the 
flag EXPAND or, if FORCE is on, without the flag NOEXPAND are expanded 
before the definition is seen by the cross-reference program, so this flag 
can also be used to select those macros you require expanded and those you 
do not. The use of ON FORCE; is highly recommended for CREF. 


18.3. Picture RLISP 
[?2?? ReWrite 277] 


Picture RLISP is an ALGOL-like graphics language for Teleray, HP2648a and 
Tektronix, in which graphics Model primitives are combined into complete 
Models for display. Model primitives include: 


Piz1x,y,2); 
A point (y, and z may be omitted, default to 0). 


PS:=P1_ P2_... Pn; 


A Point Set is an ordered set of Points (Polygon). 


.G := PS1 & PS2 & ... PSn; 
A Group of Polygons. 


Point Set Modifiers 
alter the interpretation of Point Sets within their scope. 


BEZIER() causes the point-set to be interpreted as the specification 
points for a BEZIER curve, open pointset. - 


BSPLINE() does the same for a Bspline curve, closed pointset. 


TRANSFORMS: 
Mostly return a transformation matrix. 


Translation: 


Move the specified amount along the specified axis. 
XMOVE (deltaX); YMOVE (deltaY); ZMOVE(deltaZ); 
MOVE (deltaX, deltaY, deltaZ); 


Scale: Seale the Model SCALE (factor) XSCALE(factor); YSCALE(factor); 
ZSCALE(factor); 


y 


LJ 
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18.2.2. Usage 

RCREF should be used in PSL:RLISP. To make a file FILE.CRF which is a 
cross reference listing for files FILE1.EX1 and FILE2.EX2 do the following 
in RLISP: 


PSL:RLISP 

LOAD RCREF; % RCREF is now autoloading, so this may be omitted. 
OUT "file.erf"; % later, CREFOUT ... 

ON CREF; 

IN "file1.ex1","file2.ex2"; 

OFF CREF; 


SHUT "file.crf"; % later CREFEND 


To process more files, more IN statements may be added, or the IN statement 
may be changed to include more files. 


18.2.3. Options 


! *CREFSUMMARY (Initially: NIL) flag 


If the flag CREFSUMMARY is GN (or !*CREFSUMMARY is true in LISP), 
then only the summary (see 1 above) is produced. 


Functions with the flag NOLIST are not examined or output. Initially, 
all Standard LISP functions are so flagged. (In fact, they are kept on a 
list NOLIST!*, so if you wish to see references to ALL functions, then CREF 
should be first loaded with the command LOAD RCREF, and this variable then 
set to NIL). (RCREF is now autoloading.) 


NOLIST!* (Initially: 
(AND COND LIST MAX MIN OR PLUS PROG PROG2 PROGN TIMES LAMBDA ABS ADD1 


LAA MEDIDA | EA AMIA DEA DEE | EAT | IAE A SS a 


A A a ee ck AAA Ee e 


CADDR CDAAR CDADR CDDAR CDDDR CAAAAR CAAADR CAADAR CAADDR CADAAR 
CADADR CADDAR CADDDR CDAAAR CDAADR CDADAR CDADDR CDDAAR CDDADR CDDDAR 


DIFFERENCE DIGIT DIVIDE DM EJECT EQ EQN EQUAL ERROR ERRORSET EVAL 
EVLIS EXPAND EXPLODE EXPT FIX FIXP FLAG FLAGP FLOAT FLOATP FLUID 
FLUIDP FUNCTION GENSYM GET GETD GETV GLOBAL GLOBALP GO GREATERP IDP 
INTERN LENGTH LESSP LINELENGTH LITER LPOSN MAP MAPC MAPCAN MAPCAR 
MAPCON MAPLIST MAX2 MEMBER MEMQ "MINUS ~ MINUSP “MIN2 MI MKVECT NCONC NOT 
NULL NUMBERP ONEP EP OPEN PAGELENGTH — PAIR PATRP PLUS2 POSN PRINC PRINT 
PRIN1 PRIN2 PROG2 PUT PUTD PUTV QUOTE QUOTIENT RDS READ READCH 


ES AB be Po ad as A A AAA. AA eee o FP cal 


REMAINDER REMD REMFLAG REMOB REMPROP RETURN REVERSE RPLACA RPLACD 


=- SASSOC SET SETQ STRINGP SUBLIS SUBST SUB1 TERPRI TIMES2 UNFLUID UPBV 


SATA A A MAA ee ES A rd 


VECTORP WRS ZEROP)) global 
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i. A list of files processed. 

ii. A list of "entry points" (functions which are not called 
or are called only by themselves). 

iii. A list of undefined functions (functions called but not 
defined in this set of functions). 

iv. A list of variables that were used non-locally but not 
declared GLOBAL or FLUID before their use. 

v. A list of variables that were declared GLOBAL but used as 
FLUIDS (i.e. bound in a function). 

vi. A list of FLUID variables that were not bound ina 
function so that one might consider declaring them 
GLOBALs. 

vii. A list of all GLOBAL variables present. 
viii. A list of all FLUID variables present. 
ix. A list of all functions present. 


b. A "global variable usage" table, showing for each non-local 
variable: 


i. Functions in which it is used as a declared FLUID or 
GLOBAL. 
ii. Functions in which it is used but not declared before. 
iii. Functions in which it is bound. 
iv. Funetions in which it is changed by SetQ. 


c. A "function usage" table showing for each function: 


i. Where it is defined. 
ii. Functions which call this function. 
iii. Functions called by it. 
iv. Non-local variables used. 


The output is alphabetized on the first seven characters of each function 
name. 


RCREF also checks that functions are called with the correct number of 
arguments. 


18.2.1. Restrictions 

Algebraic procedures in REDUCE are treated as if they were symbolic, so 
that algebraic constructs actually appear as calls to symbolic functions, 
such as AEval. 


SYSLISP procedures are not correctly analyzed. 
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SCALE 1(x.scale.factor, y.scale.factor, z.scale.factor); 


SCALE<Scale factor>;. Scale along all axes. 


Rotation: ROT( degrees); ROT(degrees, point.specifying.axis); XROT(degrees); 
YROT(degrees); ZROT(degrees) ; 


Window (z.eye,z.screen): 
The WINDOW primitives assume that the viewer is located along the 
z axis looking in the positive z direction, and that the viewing 
Window is to be centered on both the x and y axis. 


Vwport(leftclip,rightclip,topclip,bottomelip): 
The VWPORT, which specifies the region of the screen which is 
used for display. 


REPEATED (number.of.times, my.transform): 
The Section of the Model which is contained within the scope of 
the Repeat Specification is replicated. Note that REPEATED is 
intended to duplicate a sub-image in several different places on 
the screen; it was not designed for animation. 


Identifiers of other Models 
the Model referred to is displayed as if it were part of the 
current Model for dynamic display. 


Calls to PictureRLISP Procedures 

This Model primitive allows procedure calls to be imbedded within 
Models. When the Model interpreter reaches the procedure 
identifier it calls it, passing it the portion of the Model below 
the procedure as an argument. The current transformation matrix 
and the current pen position are available to such procedures as 
the values of the global identifiers GLOBAL!.TRANSFORM and 
HEREPOINT. If normal procedure eall syntax, i.e. 
proc.name (parameters), is used then the procedure is called at 
Model-building time, but if only the procedure's identifier is 
used then the procedure is imbedded in the Model. 


ERASE() Clears the screen and leaves the cursor at the origin. 


SHOW (pict) 
Takes a picture and displays it on the screen. 


ESHOW (pict) 
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Erases the whole screen and display "pict". 
HP! .INIT(), TEK!.INITC), TEL!.INIT(C) 


Initializes the operating system's view of the characteristics of 
HP2648A terminal, TEKTRONIX 4006-1 (also ADM-3A with 


Retrographics board, and Teleray-1061). 


For example, the Model 


(A _B_C & {1,2} _ B) | XROT (30) |  'TRAN ; 
4 

% PictureRLISP Commands to SHOW lots of Cubes 

% 


% Outline is a Point Set defining the 20 by 20 
% square which is part of the Cubeface 

$ 

Outline := { 10, 10} {-10, 10} 


{-10,-10} _ { 10,-10} _ (10, 10}; 


% Cubeface also has an Arrow on it 


Z 
Arrow t= {0,-1} _ 10,2) € {-1,1} _ {0,2} _ (1,1); 


% We are ready for the Cubeface 

Cubeface I= (Outline & Arrow) ¡ 'Tranz; 

% Note the use of static clustering to keep objects 
% meaningful as well as the quoted Cluster 

% to the as yet undefined transformation Tranz, 

% which results in its evaluation being 


% deferred until SHOW time 


% and now define the Cube 


Cube 2s Cubeface 
& Cubeface | XROT (180) % 180 degrees 
& Cubeface | YROT ( 90) 
& Cubeface | YROT (-90) 
& Cubeface | XROT ( 90) 
[] 
1 


Ro 


Cubeface XROT (-90); 

% In order to have a more pleasant look at 

% the picture shown on the screen we magnify 
% cube by 5 times. 

BigCube := Cube | SCALE 5; 


% Set up initial Z Transform for each cube face 
2 
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Tranz s= ZMOVE (10); 4% 10 units out 


GLOBAL! . TRANSFORM has been treated as a global variable. 
LOBAL!. TRANSFORM should be initialized as a perspective 
transformation matrix so that a viewer can have a correct 
look at the picture as the viewing location changed. 
For instance, it may be set as the desired perspective 
With a perspective window centered at the origin and 
of sereen size 60, and the observer at -300 on the z axis. 
Currently this has been set as default perspective transformation. 


BA 42 BA BABA GA TA GLA GA 


% Now draw cube 
% 

SHOW BigCube; 
a 

RP 


% Draw it again rotated and moved left 
$ 
SHOW (BigCube i XROT 20 ¡ YROT 30 | ZROT 10); 


% Dynamically expand the faces out 
$ 

Tranz sz ZMOVE 12; 

% z 
SHOW (BigCube | YROT 30 i ZROT 10); 


% Now show 5 cubes, each moved further right by 80 


% 
Tranz ts ZMOVE 10; 


% 
SHOW (Cube | SCALE 2.5 | XMOVE (-240) {| REPEATED(5, XMOVE 80)); 


? 

% Now try pointset modifier. 

% Given a pointset (polygon) as control points either a BEZIER or a 
% BSPLINE curve can be drawn. 


3 

Cpts := {0,0} _ {70,-60} _ {189,-69} _ {206,33} _ {145,130} _ (48,130) 
_ 10,847 $ 

3 


% Now draw Bezier curve 

% Show the polygon and the Bezier curve 
$% 

SHOW (Cpts € Cpts | BEZIER()); 


% Now draw Bspline curve 

% Show the polygon and the Bspline curve 
$ 

SHOW (Cpts & Cpts | BSPLINE()); 
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% Now work on the Circle 

% Given a center position and a radius a circle is drawn 
2 

SHOW ( {10,10} | CIRCLE(50)); 

% 

% Define a procedure which returns a model of 
% a Cube when passed the face to be used 

$ 

Symbolic Procedure Buildcube; 

List 'Buildcube; 

% put the name onto the property list 
Put('buildeube, 'pbintrp, 'Dobuildeube); 
Symbolic Procedure Dobuildcube Face$ 


Face & Face | XROT(180) 
& Face | YROT(90) 
& Face | YROT(-90) 
& Face | XROT(90) 
& Face i XROT(-90) ; 


% just return the value of the one statement 


Use this procedure to display 2 cubes, with and 
without the Arrow - first do it by calling 
Buildcube at time the Model is built 


T A 349 39 ya 


AMOVE (-15) £ 
XMOVE 15; 


Buildcube() |! 


t= Cubeface | 
! 'Tranz) | Buildcube() | 


(Outline 
% 
SHOW (P ¡| SCALE 5); 
% Now define a procedure which returns a Model of 
% a cube when passed the half size parameter 


Symbolic Procedure Cubemodel; 

List 'Cubemodel; 

%put the name onto the property list 
Put('Cubemodel,'Pbintrp, 'Docubemodel); 
Symbolic Procedure Docubemodel HSize; 

<< if idp HSize then HSize := eval HSize$ 


{ HSize, HSize, HSize} Š 
{-HSize, HSize, HSize} 
(-HSize, -HSize, HSize} _ 
{ HSize, -HSize, HSize} 
{ HSize, HSize, HSize} _ 
{ HSize, HSize, ~HSize} 
{-HSize, HSize, -HSize} ` 
{-HSize, -HSize, -HSize} _ 
{ HSize, -HSize, -HSize} ` 
{ HSize, HSize, -HSize} 4 
{-HSize, HSize, -HSize} 
{-HSize, HSize, HSize} & 
{-HSize, -HSize, -HSize} 


uJ 


PSL Manual 22 July 1982 Utilities 
section 18.3 page 18.9 


{-HSize, -HSize, HSize} & 
{ HSize, -HSize, -HSize} _ 
{ HSize, ~HSize, HSize} >>; 


4 Imbed the parameterized cube in some Models 


A 
n 


His!.cube := 'His!.size | Cubemodel(); 

Her!.cube := 'Hert.size | Cubemodel(); 

R := His!.cube | XMOVE (60) & 
Her!.cube | XMOVE (-60) ; 


% Set up some sizes and SHOW them 


His!.size := 50; 
Her!.size := 30; 
% 

SHOW R; 

2 

% Set up some different sizes and SHOW them again 
a 

His!.size {= 35; 
Her!.size := 60; 
% 

SHOW R; 

$ 


% Now show a triangle rotated 45 degree about the z axis. 
Rotatedtriangle := {0,0} _ {50,50} _ 
{100,0} _ {0,0} | Zrot (45); 
% 
SHOW Rotatedtriangle; 


g é 
% Define a procedure which returns a model of a Pyramid 
% when passed Y vertices of a pyramid. 
% Procedure Second,Third, Fourth and Fifth are primitive procedures 
% written in the source program which return the second, the third, 
% the fourth and the fifth element of a list respectively. 
% This procedure simply takes 4 points and connects the vertices to 
% show a pyramid. 
Symbolic Procedure Pyramid (Point4); %.point4 is a pointset 
Point & 

Third Point4 

Fifth Point4 — 

Second Point 


Fourth Point ; 


% Now give a pointset indicating Y vertices build a pyramid 
% and show it 

2 

My!.vertices := {-40,0} _ {20,-40} _ {90,20} _ {70,100}; 
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My! .pyramid := Pyramid Vertices; 


2 
SHOW ( My!.pyramid ¡ XROT 30); 


A procedure that makes a wheel with "count" 
spokes rotated around the z axis. 
in which "count" is the number specified. 
ymbolic Procedure Dowheel(spoke,count)$ 
begin scalar rotatedangle$ 
count := first count$ 
rotatedangle := 360.0 / count$ 
return (spoke | REPEATED(count, ZROT rotatedangle)) 


UN 32 32 32 39 


end$ 


% 
% Now draw a wheel consisting of 8 cubes 


A 
A 


Cubeonspoke := (Outline | ZMOVE 10 | SCALE 2) | buildcube(); 
Eight!.cubes := Cubeonspoke | XMOVE 50 | WHEEL(8); 

% 

SHOW Eight!.cubes; 


a 

“Draw a cube in which each face consists of just 

% a wheel of 8 Outlines 

4 

Flat!.Spoke := outline ¡ XMOVE 25$ 

At.Fancy!.Cube := Flat!.Spoke | WHEEL(8) | ZMOVE 50 {| Buildeube()$ 
% 

SHOW A!.Fancy!.Cube; 


b 

% Redraw the fancy cube, after changing perspective by 
% moving the observer farther out along Z axis 

g z 

GLOBAL!.TRANSFORM := WINDOW(-500,60); 

% 

SHOW A!.Fancy!.Cube; 


% 

% Note the flexibility resulting from the fact that 
% both Buildcube and Wheel simply take or return any 
% Model as their argument or value 


18.3.1. Running PictureRLISP on HP2648A and on TEKTRONIX 4006-1 Terminals 
The current version of PictureRLISP runs on HP2648A graphics terminal and 
TEKTRONIX 4006-1 computer display terminal. The screen of the HP terminal 
is 720 units long in the X direction, and 360 units high in the Y 
direction, The coordinate system used in HP terminal places the origin in 
approximately the center of the screen, and uses a domain of -360 to 360 
and a range of -180 to 180. Similarly, the screen of the TEKTRONIX 
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terminal is 1024 units long in the X direction, and 780 units high in the Y 
direction, The same origin is used but the domain is -512 to 512 in the X 
direction and the range is -390 to 390 in the Y direction. 


Procedures HP!.INIT and TEK!.INIT are used to set the terminals to 
graphics mode and initiate the lower level procedures on HP and TEKTRONIX 
terminals respectively. Basically, INIT procedures are written for 
different terminals depending on their specific characteristics. Using 
INIT procedures keeps terminal device dependence at the user's level to a 
minimum. 


18.4. Tools for Defining Macros 
The following (and other) macro utilities are in the file PU:USEFUL.SL; 


1 
use LOAD(useful) to access. See PH:USEFUL.HLP for more information. 


18.4.1. DefMacro 
DefMacro (A:id, B:form, [C:form]): id macro 


DefMacro is a useful tool for defining macros. A DefMacro form 
looks like 


(DEFMACRO <NAME> <PATTERN> <S1> <S2> ... <Sn>) 


The <PATTERN> is an S-expression made of pairs and ids. It is 
matched against the arguments of the macro much like the first 
argument to DeSetQ. All of the non-NIL ids in <pattern> are 
local variables which may be used freely in the body (the <Si>). 
If the macro is called the <Si> are evaluated as in a ProgN with 
the local variables in <pattern> appropriately bound, and the 
value of <Sn> is returned. DefMacro is often used with 
BackQuote. 


1 
Useful was written by D. Morrison. 
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18.4.2. BackQuote 
Note that the special symbols described below only work in LISP syntax, 


not RLISP. In RLISP you may simply use the functions BackQuote, UnQuote, 
and UnQuoteL. Load USEFUL to get the BackQuote function. 


The backquote symbol """ is a Read macro which introduces a quoted 
expression which may contain the unquote symbols comma "," and comma-atsign 
",@", An appropriate form consisting of the unquoted expression calls to 
the function Cons and quoted expressions are produced so that the resulting 
expression looks like the quoted one except that the values of the unquoted 
expressions are substituted in the appropriate place. ",@" splices in the 
value of the subsequent expression (i.e. strips off the outer layer of 
parentheses). Thus 

“(a (b ,x) cd ,@x e f) 
is equivalent to 

(cons 'a (cons (list 'b x) (append '(c d) (append x '(e f))))) 
In particular, if x is bound to (1 2 3) this evaluates to 


ta (b (12 3))cd123e f) 


BackQuote (A:form): form macro 


Function name for back quote `. 


UnQuote (A:any): Undefined fexpr 
Function name for comma ,. It is an error to Eval this function; 
it should occur only inside a BackQuote. 

UnQuoteL (A:any): Undefined fexpr 
Function name for comma-atsign ,@. It is an error to Eval this 


function; it should only occur inside a BackQuote. 


18.4.3. Sharp-Sign Macros 

USEFUL defines several MACLISP style sharp sign read macros. Note that 
these only work with the LISP reader, not RLISP. Those currently included 
are 


Y : this is like the quote mark ' but is for FUNCTION instead of QUOTE. 
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#/ i this returns the numeric form of the following character read 


without raising it. For example #/a is 97 while #/A is 65. #\ : This is 
a read macro for the CHAR macro, described in the PSL manual. Not that the 
argument is raised, if *RAISE it non-nil. For example, ¿Ma = #\A = 65, 
while ¡Mila = #\(lower a) = 97. Char has been redefined in USEFUL to be 
slightly more table driven -- users can now add new "prefixes" such as META 
or CONTROL: just hang the appropriate function (from integers to integers) 
off the char-prefix-function property of the "prefix", A LARGE number of 
additional alias for various characters have been added, including all the 
"standard" ASCII names like NAK and DC1. 


#. : this causes the following expression to be evaluated at read time. 
For example, ‘(1 2 #.(plus 1 2) 4) reads as (1 2 3 4) 


#+ : this reads two expressions, and passes them to the if system macro. 
That is, the first should be a system name, and if that is the current 
system the second argument is returned by the reader. If not, the next 
expression is returned. 


fm: #- is similar, but causes the second arg to be returned only if it 
is NOT the current system. 


18.4.4. MacroExpand 


MacroExpand (A:form, [B:id]): form macro 


MacroExpand is a useful tool for debugging macro definitions. If 
given one argument, MacroExpand expands all the macros in that 
form. Often one wishes for more control over this process. For 
example, if a macro expands into a Let, we may not wish to see 
the Let itself expanded to a lambda expression. Therefore 
additional arguments may be given to MacroExpand. If these are 
Supplied, they should be macros, and only those specified are 
expanded. 


18.4.5. DefLambda 


DefLambda (): macro 


Yet another little (two line) macro has been added to USEFUL: 


DefLambda. This defines a macro much like a substitution macro 
(smacro) except that it is a lambda expression. Thus, modulo 


redefinability, it has the same semantics as the equivalent expr. 
It is mostly intended as an easy way to open compile things. For 
example, we would not normally want to define a substitution 
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macro for a constructor (NEW-FOO X) which maps into (CONS X X), 
in case X is expensivee to compute or, far worse, has side 
effects. (DEFLAMBDA NEW-FOO (X) (CONS X X)) defines it as a 
macro which maps (NEW-FCO (SETQ BAR (BAZ))) to 
((LAMBDA (X) (CONS X X)) (SETQ BAR (BAZ))). 


18.5. Simulating a Stack 


The following macros are in the USEFUL package. They are convenient for 
adding and deleting things from the head of a list. 


Push (ITM:any, STK:list): any macro 
(PUSH ITEM STACK) 
is equivalent to 


(SETF STACK (CONS ITEM STACK) ) 


Pop (STK:list): any macro 
(POP STACK) | 
does 
(SETF STACK (CDR STACK)) 


and returns the item popped off STACK, An additional argument 
may be supplied to Pop, in which case it is a variable which is 
SetQ'd to the popped value. 


18.6. DefStruct 


Load DEFSTRUCT; to use the functions described below, or FAST!-DEFSTRUCT 
to use those functions but with fast vector operations used. DefStruct is 
Similar to the Spice (Common) LISP/LISP machine/MacLISP flavor of struct 
definitions, and is expected to be subsumed by the Mode package. It is 

2 
implemented in PSL as a function which builds access macros and fns for 
"typed" vectors, including constructor and alterant macros, a type 


2 
Defstruct was implemented by Russ Fish. 
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predicate for the structure type, and individual selector/assignment fns 
for the elements. DefStruct understands a keyword-option oriented 
structure specification. DefStruct is now autoloading. 


First a few miscellaneous functions on types, before getting into the 
depths of defining DefStructs: 


DefstructP (NAME:id): extra-boolean expr 
This is a predicate that returns non-NIL (the Defstruct 
definition) if NAME is a structured type which has been defined 
using Defstruct, or NIL if it is not. 

DefstructType (S:struct): id expr 
This returns the type name field of an instance of a structured 
type, or NIL if S cannot be a Defstruct type. 

SubTypeP (NAME1:id, NAME2:id): boolean expr 
This returns true if NAME1 is a structured type which has been 
t:Included in the definition of structured type NAME2, possibly 


through intermediate structure definitions. (In other words, the 
selectors of NAME1 can be applied to NAME2.) 


Now the function which defines the beasties, in all its gory glory: 


Defstruct (NAME~AND-OPTIONS: {id,list}, [SLOT-DESCS: {id,list}]): id fexpr 


ce A i 


Defines a record-structure data type. A general call to 
Defstruct looks like this: (in RLISP syntax) 


defstruct( struct-name( option-1, option-2, ... ), 
slot-description-1, 
slot-description-2, 
); 
% (The name of the defined structure is returned.) 


Slot-descriptions are: 


slot-name( default-init, slot-option-1, slot-option-2, +... ) 
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Struct-name and slot-name are ids. If there are no options following a 
name in a spec, it can be a bare id with no option argument list. Tne 
default-init form is optional and may be omitted. The default-init form is 
evaluated EACH TIME a structure is to be constructed and the value is used 
as the initial value of the slot. Options are either a keyword id, or the 
keyword followed by its argument list. Options are described below. 


A call to a constructor macro has the form: 


MakeThing( slot-name-1( value-expr-1 ), 
slot-name-2( value-expr-2 ), 


O a. 


The slot-name:value lists override the default-init values which were part 
of the structure definition. Note that the slot-names look like unary 
functions of the value, so the parens can be left off. A call to MakeThing 
with no arguments of course takes all of the default values. The order of 
evaluation of the default-init forms and the list of assigned values is 
undefined, so code should not depend upon the ordering. 


Implementors Note: Common/LispMachine Lisps define it this way, but Is 
this necessary? It wouldn't be too tough to make the order be the same as 
the struct defn, or the argument order in the constructor call. Maybe they 
think such things should not be advertised and thus constrained in the 
future. Or perhaps the theory is that constructs such as this can be 
compiled more efficiently if the ordering is flexible?? Also, should the 
overridden default-init forms be evaluated or not? I think not. 


The alterant macro calls have a similar form: 


AlterThing( thing, 
slot-name-1 value-expr-1, 
slot-name-2 value-expr-2, 


A de 


The first argument evaluates to the struct to be altered. (The optional 
parens were left off here.) This is just a multiple-assignment form, which 
eventually goes through the slot depositors. Remember that the slot-names 
are used, not the depositor names. (See !:Prefix, below.) The altered 
structure instance is returned as the value of an Alterant macro. 


Implementators note: Common/LispMachine Lisp defines this such that all 
of the slots are altered in parallel AFTER the new value forms are 
evaluated, but still with the order of evaluation of the forms undefined. 


LJ 


vd 


2) 
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This seemed to lose more than it gained, but arguments for its worth will 
be entertained. 


18.6.1. Options 

Structure options appear as an argument list to the struct-name. Many of 
the options themselves take argument lists, which are sometimes optional. 
Option ids all start with a colon (!:), on the theory that this 
distinguishes them from other things. 


By default, the names of the constructor, alterant and predicate macros 
are MakeName, AlterName and NameP. "Name" is the struct-name. The 
t:Constructor, !:Alterant, and !:Predicate options can be used to override 
the default names. Their argument is the name to use, and a name of NIL 
causes the respective macro not to be defined at all. 


The !:Creator option causes a different form of constructor to be 
defined, in addition to the regular "Make" constructor (which can be 
Suppressed.) As in the !:Constructor option above, an argument supplies 
the name of the macro, but the default name in this case is CreateName. A 
call to a Creator macro has the form: 


CreateThing( slot-value-1, slot-value-2, +... ); 


ALL of the slot-values of the structure MUST BE PRESENT, in the order they 
appear in the structure definition. No checking is done, other than 
assuring that the number of values is the same as the number of slots. For 
obvious reasons, constructors of this form ARE NOT RECOMMENDED for 
structures with many fields, or which may be expanded or modified. 


Slot selector macros may appear on either the LHS or the RHS of an 
assignment. They are by default named the same as the slot-names, but can 
be given a common prefix by the !:Prefix option. If !:Prefix does not have 
an argument, the structure name is the prefix. If there is an argument, it 
should be a string or an id whose print name is the prefix. 


The !:Include option allows building a new structure definition as an 
extension of an old one. The required argument is the name of a previously 
defined structure type. The access functions for the slots of the source 
type also works on instances of the new type. This can be used to build 
hierarchies of types. The source types contain generic information in 
common to the more specific subtypes which !:Include them. 


The !:IncludeInit option takes an argument list of "slot-name(default- 
init)" pairs, like slot-descriptors without slot-options, and files them 
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away to modify the default-init values for fields inherited as part of the 
t: Included structure type. 


18.6.2. Slot Options 

Slot-options include the !:Type option, which has an argument declaring 
the type of the slot as a type id or list of permissible type ids. This is 
not enforced now, but anticipates the Mode system structures. 


The !:UserGet and !:UserPut slot-options allow overriding the simple 
vector reference and assignment semantics of the generated selector macros 
with user-defined functions. The !:UserGet FNAME is a combination of the 
Slot-name and a !:Prefix if applicable. The !:UserPut FNAME is the same, 
with "Put" prefixed. One application of this capability is building 
depositors which handle the incremental maintenance of parallel data 
structures as a side effect, such as automatically maintaining display file 
representations of objects which are resident in a remote display processor 
in parallel with modifications to the LISP structures which describe the 
objects. The Make and Create macros bypass the depositors, while Alter 
uses them. 


18.6.3. A Simple Example 


(Input lines have a "> " prompt at the beginning.) 


> % (Do definitions twice to see what functions were defined.) 
> macro procedure TWICE u; list( 'PROGN, second u, second u ); 
TWICE 


> % A definition of Complex, structure with Real and Imaginary parts. 
> % Redefine to see what functions were defined. Give O Init values. 
> TWICE 

> Defstruct( Complex( !:Creator(Complex) ), R(0), I(0) ); 

#** Function ‘MAKECOMPLEX' has been redefined 

*#** Function ‘“ALTERCOMPLEX' has been redefined 

*** Function 'COMPLEXP' has been redefined 

*** Function "COMPLEX' has been redefined 

£** Function `R! has been redefined 

*** Function *PUTR' has been redefined 

*** Function *I' has been redefined 

**%* Function *PUTI' has been redefined 

*** Defstruct *COMPLEX' has been redefined 

COMPLEX 


> CO := MakeComplex(); % Constructor with default inits. 
[COMPLEX O 0] 


> ComplexP C0;% Predicate. 
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> C1:=MaxeComplex( R 1, 12); % Constructor with named values. 

[COMPLEX 1 2] 


> R(C1); 1(C1);% Named selectors. 
1 
2 


> C2:=Complex(3,%4) % Creator with positional values. 
[COMPLEX 3 4] 


> AlterComplex( C1, R(2), 1(3) ); % Alterant with named values. 
[COMPLEX 2 3] 


> C1; 
[COMPLEX 2 3] 


> R(C1):=5; 1(C1):=6; % Named depositors. 
5 
6 


> C1; 
[COMPLEX 5 6] 


> % Show use of Include Option. (Again, redef to show fns defined.) 
> TWICE ] i 

> Defstruct( MoreComplex( !:Include(Complex) ), Z(99) ); 

*** Function "MAKEMORECOMPLEX' has been redefined 

*X* Function "ALTERMORECOMPLEX' has been redefined 

*** Function ~MORECOMPLEXP! has been redefined 

#*% Function `Z' has been redefined 

*** Function *PUTZ' has been redefined 

*** Defstruct ‘“MORECOMPLEX! has been redefined 

MORECOMPLEX 


> MO := MakeMoreComplex(); 
[MORECOMPLEX 0 O 99] 


> M1 := MakeMoreComplex( R 1, I 2, Z 3); 
[MORECOMPLEX 1 2 3] 


> R C1; 

5 

> R M1; 

1 

> % A more complicated example: The structures which are used in the 
> % Defstruct facility to represent defstructs. (The EX prefix has 
> % been added to the names to protect the innocent...) 
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> Def struct ( 

> EXDefstructDescriptor( !:Prefix(EXDsDesc), !:Creator ), 


>DsSize(!:Type int ), 


% (Upper Bound of vector.) 


>Prefix(!:Type string ), 
>SlotAlist( 
>ConsName ( 
>AltrName( 
>PredName ( 
>CreateName ( 
>Include( 
>InclInit( 


> ae 
HEX 
Leer 
xx% 
ere 
xx% 
PE 
EXA 
RX 
er 
EXA 
LIX 
HX 
xx 
xx% 
AER 
Pern 
xx% 
¥%% 
Per 
Ex 

PE 
ETT 
*** 


Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 
Function 


alist ), % (Cdrs are SlotDescriptors.) 
fnld ), 

fnId ), 

fnId ), 

fnld ), 

typeid ), 

alist ) 


!;Type 
! :Type 
i Type 
i :Type 
t! ¿Type 
! :Type 
! ¿Type 


` MAKEEXDEFSTRUCTDESCRIPTOR!' has been redefined 
`ALTEREXDEFSTRUCTDESCRIPTOR! has been redefined 
“EXDEFSTRUCTDESCRIPTORP' has been redefined 
`CREATEEXDEFSTRUCTDESCRIPTOR' has been redefined 
“EXDSDESCDSSIZE' has been redefined 

` PUTEXDSDESCDSSIZE' has been redefined 
`EXDSDESCPREFIX' has been redefined 

` PUTEXDSDESCPREFIX' has been redefined 
“EXDSDESCSLOTALIST! has been redefined 
“PUTEXDSDESCSLOTALIST' has been redefined 
`EXDSDESCCONSNAME' has been redefined 
“PUTEXDSDESCCONSNAME! has been redefined 
“EXDSDESCALTRNAME! has been redefined 

` PUTEXDSDESCALTRNAME* has been redefined 
“EXDSDESCPREDNAME* has been redefined 
*PUTEXDSDESCPREDNAME' has been redefined 
“EXDSDESCCREATENAME' has been redefined 

` PUTEXDSDESCCREATENAME? has been redefined 
“EXDSDESCINCLUDE' has been redefined 

` PUTEXDSDESCINCLUDE' has been redefined 
“EXDSDESCINCLINIT' has been redefined 
“PUTEXDSDESCINCLINIT? has been redefined 


Defstruct *EXDEFSTRUCTDESCRIPTOR' has been redefined 
EXDEFSTRUCTDESCRIPTOR 


> TWICEZ% Redef to show fns generated. 
> Defstruct( 


> EXSlotDescriptor( !:Prefix(EXSlotDesc), !:Creator ), 
>SlotNum( t:Type int ), 

>InitForm( t:Type form ), 

>SlotFn(!:Type fnId ), % Selector/Depositor id. 

>SlotType( t:Type type ), % Hm... 

>UserGet ( !;Type boolean ), 

>User Put ( !:Type boolean ) 

> ); 


*** Function `MAKEEXSLOTDESCRIPTOR! has been redefined 
*** Function `ALTEREXSLOTDESCRIPTOR!' has been redefined 
*** Function `EXSLOTDESCRIPTORP! has been redefined 


PSE 
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FES 
HEX 
eX 
EX 
KER 
ARA 
XA 
FRX 
REX 
RE 
RF 


Function ~CREATEEXSLOTDESCRIPTOR' has been redefined 
Function ~“EXSLOTDESCSLOTNUM' has been redefined 
Function ~PUTEXSLOTDESCSLOTNUM!' has been redefined 
Function “EXSLOTDESCINITFORM' nas been redefined 
Function *PUTEXSLOTDESCINITFORM! has been redefined 
Function ~EXSLOTDESCSLOTFN' has been redefined 
Function ~PUTEXSLOTDESCSLOTFN' has been redefined 
Function “EXSLOTDESCSLOTTYPE' has been redefined 
Function *PUTEXSLOTDESCSLOTTYPE' has been redefined 
Function *EXSLOTDESCUSERGET' has been redefined 
Function *PUTEXSLOTDESCUSERGET* has been redefined 
Funetion “EXSLOTDESCUSERPUT' has been redefined 
Function *PUTEXSLOTDESCUSERPUT' has been redefined 
Defstruct *EXSLOTDESCRIPTOR' has been redefined 


EXSLOTDESCRIPTOR 


> END; 


NIL 


18.7. DefConst 


DefConst ([U:id, V:number]): Undefined a macro 


DefConst is a simple means for defining and using symbolic 
constants, as an alternative to the heavy-handed NEWNAM or: DEFINE 
facility in REDUCE/RLISP. Constants are defined thus: 
DefConst(FooSize, 3); or as sequential pairs: 


DEFCONST(FOOSIZE, 3, 
BARSIZE, 4); 
Const (U:id): number macro 
They are referred to by the macro Const, so 
CONST(FOOSIZE) 


would be replaced by 3. 


18.8. Find 


These functions take a string or id, map the oblist to collect a list of 
ids with Prefix or Suffix as given: 
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FindPrefix (KEY:{id, string}): id-list expr 


Scans current id-hash-table for an id whose prefix matches KEY. 


FindSuffix (KEY:{id, string}): id-list expr 


Scans current id-hash-table for an id whose suffix matches KEY. 


Thus 
X:=FindPrefix '!*; Finds all ids starting with * 
Use the 'GSORT' package to sort the list: 


Gsort(X,'Idsort); 


See Section 7.4 for more information about sorting functions. 


18.9. Hashing Cons 


HCONS is a loadable module. The HCons function creates unique dotted 
pairs. In other words, HCons(A, B) Eq HCons(C, D) if and only if A Eq C 
and B Eq D. This allows very rapid tests for equality between structures, 
at the cost of expending more time in creating the structures. The use of 
HCons may also save space in cases where lists share a large amount of 
common substructure, since only one copy of the substructure is stored, 


The system works by keeping a hash table of all pairs that have been 
created by HCons. (So the space advantage of sharing substructure may be 
offset by the space consumed by table entries.) This hash table allows the 
system to store property lists for pairs--in the same way that LISP has 
property lists for identifiers. 


Pairs created by HCons SHOULD NOT be modified with RplacA and RplacD. 
Doing so will make the pair hash table inconsistent, as well as being very 
likely to modify structure shared with something that you don't wish to 
change. Also note that large numbers may be equal without being eq, so the 
HCons of two large numbers may not be Eq to the HCons of two other numbers 
that appear to be the same. (Similar warnings hold for strings and 
vectors.) 


The following "user" functions are provided by HCONS: 


ol 


LJ 
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HCons (({U:any]): pair macro 
Tne HCons macro takes one or more arguments and returns their 


"hashed cons" (right associatively). Two arguments corresponds 
to a call of Cons. 


HList ([U:any]): list nexpr 


HList is the "HCONS version" of the List function. 


HCopy (U:any): any macro 


HCopy is the HCONS version of the Copy function. Note that HCopy 
serves a very different purpose than Copy, which is usually used 
to copy a structure so that destructive changes can be made to 
the copy without changing the original. HCopy only copies those 
parts of the structure which haven't already been "Consed 
together" by HCons. 


HAppend (U:list, V:list): list expr 


HCons version of Append. 


HReverse (U:list): list expr 
HCons version of Reverse. 
The following two functions can be used to "Get" and "Put" properties for 


pairs or identifiers. The pairs for these functions must be created by 
HCons. These functions are known to the SetF macro. 


Extended-Put (U:fid, pair}, IND:id, PROP:any): any expr 
Extended-Get (U:fid, pair), IND:any): any expr 


18.10. Graph-to-Tree 


GRAPH-TO-TREE is a loadable module. For resident functions printing 
circular lists see Section 16.9. 
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Graph-to-Tree (A:form): form expr 


The function Graph-to-Tree copies an arbitrary s-expression, 
removing circularity. It does NOT show non-circular shared 
structure, Places where a substructure is Eq to one of its 
ancestors are replaced by non-interned ids of the form <n> where 
n is a small integer. The parent is replaced by a two element 
list of the form (<n>: u) where the n's match, and u is the 
(de-circularized) structure. This is most useful in adapting any 
printer for use with circular structures. 


CPrint (A:any): NIL expr 


The function CPrint, also defined in the module GRAPH-TO-TREE, is 
simply (PrettyPrint (Graph-to-Tree X)). 


Note that - GRAPH-TO-TREE is very embryonic. It is MUCH more inefficient 
than it needs to be, heavily consing. A better implementation would use a 
stack (vector) instead of lists to hold intermediate expressions for 
comparison, and would not copy non-circular structure. In addition 
facilities should be added for optionally showing shared structure, for 
performing the inverse operation, and for also editing long or deep 
Structures. Finally, the output representation was chosen at random and 
can probably be improved, or at least brought in line with CL or some other 
Standard. 


18.11. Inspect Utility 


INSPECT is a loadable module. 


Inspect (): expr 


This is a simple utility which scans the contents of a source 
file to tell what functions are defined init. It will be 
embellished slightly to permit the on-line querying of certain 
attributes of files. Inspect reads one or more files, printing 
and collecting information on defined functions. 


Usage: 
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LOAD INSPECT; 


INSPECT "file-name"; % Scans the file, and prints proc 
% names. It also 
% builds the lists ProcedureList!* 
% FileList!* and ProcFileList!* 


% File-Name can IN other files 


On the Fly printing is controlled by !*PrintInspect, default is 
T. Other lists built include FileList!* and ProcFileList!¥*, which 
is a list of (procedure . filename) for multi-file processing. 


For more complete process, do: 


LOAD Inspect; 

Off PrintInspect; 

InspectOut(); % Later will get a file Name 
IN tag et 

EN 

InspectEnd; 


Now use GSort, etc. to process the lists. 


18.12. Trigonometric and Other Mathematical Functions 


The MATHLIB package contains some useful mathematical functions as an 
interim until more efficient functions can be defined in SYSLISP, or higher 
precision BIGFLOAT's implemented using Sasaki's package. This BigFloat 
package has more functions, with user controlled precision; the FLOAT 


3 


package should define equivalent functions. 


Ceiling (N:number): integer _expr 


Returns the largest integer smaller than its argument. 


3 
MATHLIB consists of contributions by M. Griss, E. Benson, D. Morrison, 
W. Galway and D. Irish. 
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Round (N:number): integer expr 


Rounds to the closest integer. Kind of sloppy -- it's biased if 
the digit causing rounding is a five. 


The trigonometric functions usually expect Radians (=PI*degrees/180), 
except as indicated. 


DegreesToRadians (X:number): number expr 

RadiansToDegrees (X:number): number expr 

RadiansToDMS (X:number): number expr 
Converts degrees, minutes, seconds to radians. 


DegreesToRadians(Degs+Mins/60.0+Sex/3600.0) 


DMSToRadians (DEGS:number, MINS:number, SEX:number): number expr 
Sin (X:number): number. : expr 


Accurate to about 6 decimal places, so long as the argument is of 
commensurate precision. This, of course, is NOT true for large 
arguments, Since they come in with small precision. 


ScaledSine (X:number): number | expr 


This assumes its argument is scaled to between O and pi/2. 


Cos (X:number): number expr 
Accurate to about 6 decimal places, so long as the argument is of 
commensurate precision. This, of course, is NOT true for large 
arguments, since they come in with small precision. 


ScaledCosine (X:number): number expr 


Expects its argument to be between O and pi/2. 


Tan (X:number): number expr 


Accurate to about 6 decimal places, so long as the argument is of . 
commensurate precision. This, of course, is NOT true for large 
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arguments, since they come in with small precision. 


Cot (X:number): number 


Accurate to about 6 decimal places, so long as the argument is of 
This, of course, is NOT true for large 
arguments, since they come in with small precision. 


commensurate precision. 


22 July 1982 


ScaledTangent (X:number): number 


Expects its argument to be between 0 and pi/4. 


ScaledCotangent (X:number): number 


Expects its argument to be between O and pi/4. 


Sec (X:number): number 


Cse (X:number): number 


SinD (X:number): number 


X in Degrees, converted to 


CosD (X:number): number 


X in Degrees, converted to 


TanD (X:number): number 


X in Degrees, converted to 


CotD (X:number): number 


X in Degrees, converted to 


SecD (X:number): number 


X in Degrees, converted to 


radians. 


radians. 


radians. 


radians. 


radians. 
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expr 


expr 


expr 


expr 


expr 


expr 


expr 


expr 


expr 


expr 
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CscD (X:number): number 


X in Degrees, converted to radians. 
Asin (X:number): number 
Acos (X:number): number 
CheckedArcCosine (X:number): number 
Atan (X:number): number 
Acot (X:number): number 


CheckedArcTangent (X:number): number 


This assumes it's argument is in the range O <z x <z 1. 


Asec (X:number): number 
Aesc (X:number): number 


AsinD (X:number): number 


X in Degrees, converted to radians. 


AcosD (X:number ): number 


X in Degrees, converted to radians. 


AtanD (X:number): number 


X in Degrees, converted to radians. 


AcotD (X:number): number 


X in Degrees, converted to radians, 
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expr 


expr 


expr 


expr 


expr 


expr 


expr 


expr 


expr 


expr 


expr 


expr 


expr 
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AsecD (X:number): number expr 
X in Degrees, converted to radians. 

AcscD (X:number): number expr 
X in Degrees, converted to radians. 

Sqrt (N:number): number expr 


Simple Newton-Raphson floating point square root calculator, 
warranteed against truncation errors, etc. 


Exp (X:number): number 


Returns the exponential (i.e. e**x) of its float argument as a 
float. The argument is scaled to the interval -ln 2 to 0, and 
Taylor series expansion used (formula 4.2.45 on page 71 of 


Abramowitz and Stegun, "Handbook of Mathematical Functions"). 


Log (X:number): number 


CheckedLogarithm (X:number): number 


Log2 (X:number): number 


Log10 (X:number): number 


Random (): number 


The declarations below constitute a linear, congruential random 
number generator (see Knuth, "The Art of Computer Programming: 
Volume 2: Seminumerical Algorithms", pp. 9-24). With the given 
constants it has a period of 392931 and potency 6. To have 


deterministic behavior, set RANDOM!-SEED. 


Constants are: 6 2 
modulus: 392931 2 3 * 7 * 11 
multiplier: 232 = 3 * 7 * 11 + 1 
increment: 65537 is prime 


expr 


expr 


expr 


expr 


expr 


expr 
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L??? Would benefit from being recoded in SYSLISP, when full 
word integers should be used with "automatic" modular 
arithmetic (see Knuth). Perhaps we should have a longer 


period version? ???] 


The following constants have been defined: 


put('Number2Pi,'NewNam, 6.2831853); 

put ('NumberPi,'NewNam, 3. 1415927); 

put ( 'NumberPi!/2,'NewNam, 1.5707963); 
put('NumberPi!/4,'NewNam,0.78539816); 
put ( 'Number 3Pi!/4, 'NewNam, 2. 3561945); 
put ( 'Number!-2Pi,'Newnam,-6.2831853); 
put ( 'Number!-Pi,'NewNam,-3. 1415927); 

put ( 'Number !-Pi!/2,'NewNam,-1.5707963); 
put ( 'Number !-Pi!/4,'NewNam,-0.78539816); 


put ( 'SmallestFloNum, 'NewNam,(1/1.0e38)); %/ Fix for new Token 
% scanner 

put('SgrtTolerance, 'NewNam,0.0000001); 

put ( 'NaturalLog2,'NewNam,0.69314718); 

put ( 'NaturalLog10, 'NewNam, 2. 3025851); 
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19.1. Introduction 


The functions and facilities in the PSL LISP/SYSLISP compiler and 
supporting loaders (LAP and FASL) are described in this Chapter. 


19.2. The Compiler 


The compiler is a version of the Portable LISP Compiler [Griss 81], 
1 
modified and extended to more efficiently support both LISP and SYSLISP 


1 
Many of the recent extensions to the PLC were implemented by John 
Peterson. 
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compilation. See the later Sections in this Chapter and Refs. [Griss 81] 
and [Benson 81] for more details. 


19.2.1. Compiling Functions into Memory 


1*COMP (Initially: NIL) flag 


If the compiler is loaded (which is usually the case, otherwise 
execute LOAD COMPILER;), turning on the flag !*COMP (via on comp; 
in RLISP) causes all subsequent procedure definitions of 
appropriate type to be compiled automatically and a message of 
the form 


<function-name> COMPILED, <words> WORDS, <words> LEFT 


to be printed. The first number is the number of words of binary 
program space the compiled function took, and the second number 
the number of words left unused in binary program space. See 
!*PWRDS in Chapter 12. 


Currently, exprs, fexprs, nexprs and macros may be compiled. This is 
controlled by a flag ('COMPILE) on the property list of the procedure type. 


If desired, uncompiled functions already resident may be compiled by 
using 


Compile (NAMES:id-list): any | expr 


19.2.2. Compiling Functions into FASL Files 
In order to produce files that may be input using Load or FaslIn, the 
FaslOut and FaslEnd pair may be used in RLISP mode: 


FaslOut (FILE:string): NIL | expr 


All subsequent S-expressions and function definitions typed in or 
input from files are processed by the Compiler, LAP and FASL as 
needed, and output to FILE. Functions are compiled and partially 
assembled, and output as in a compressed binary form, involving 
blocks of code and relocation bits. This activity continues 
until the function: 


FaslEnd (): NIL expr 


terminates this process, 


wed 
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The FaslOut and FaslEnd pair also use the DFPRINT!* mechanism, turning on 
the flag !¥*DEFN, and redefining DFPRINT!* to trap the parsed input in the 
RLISP top-loop. Currently this is not useable from pure LISP level. 


[??? Fix, by adding !*DEFN mechanism to basic top-loop. ???] 


19.2.3. Loading FASL Files 
Two convenient procedures are available for loading FASL files (.b files 
on the VAX); see Section 19.2.2 for information on producing FASL files. 


Load ([{FILE:{string, id}]): NIL macro 


Each FILE is converted into a file name of the form 
"/u/local/lib/psl/file.b" on the VAX, "pl:file.b" on the DEC-20. 
An attempt is made to execute the function FaslIn on it. Once 
loaded, the symbol FILE is added to the GLOBAL variable 


OPTIONS! *, A FLAG 'LOADED is placed on the property list of FILE 
to prevent subsequent reloading. 


FaslIn (FILENAME:string): NIL expr 
This is an efficient binary read loop, which fetches blocks of. 
code, constants and compactly stored ids. It uses a bit-table to 


relocate code and to identify special LISP-oriented constructs. 
FILENAME must be a complete file name. 


Imports (): expr 
[??? Describe FASL format in more detail ???] 
19.2.4. Functions to Control the Time When Something is Done 
Which expressions are evaluated during compilation ONLY, which output to 
the file for LOAD TIME evaluation, and which do both (such as macro 
definitions) can be controlled by the properties 'EVAL and 'IGNORE on 
certain function names, or the following functions. 
CommentOutCode (U:form): NIL macro 
Comment out a single expression; use <<U>> to comment out a block 
of code. 
CompileTime (U:form): NIL expr 


Evaluate the expression U at compile time only, such as defining 
auxiliary smacros and macros that should not go into the file. 
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Certain functions have the FLAG 'IGNORE on their property lists 
to achieve the same effect. E.g. FLAG('(LAPOUT LAPEND),'*IGCNORE) 
nas been done. 


BothTimes (U:form): U:form expr 


Evaluate at compile and load time. This is equivalent in effect 
to executing Flag('(f1 £2),'EVAL) for certain functions. 


LoadTime (U:form): U:form expr 


Evaluate at load time only. Should not even compile code, just 
pass direct to file. 


[??? EVAL and IGNORE are for compatibility, and enable the above sort 
of functions to be easily written. The user should AVOID EVAL and 
IGNORE flags, if Possible ???] 


19.2.5. Order of Functions for Compilation 

Non-expr procedures must be defined before their use in a compiled 
function, since the compiler treats the various function types differently. 
Macros are expanded and then compiled; the argument list fexprs quoted; the 
arguments of nexprs are collected into a single list. Sometimes it is 
convenient to define a Dummy version of the function of appropriate type, 
to be redefined later. This acts as an "External or Forward" declaration 
of the function. 


[222 Add such a declaration. ???] 


19.2.6. Fluid and Global Declarations 

The FLUID and GLOBAL declarations must be used to indicate variables that 
are to be used as non-LOCALs in compiled code. Currently, the compiler 
defaults variables bound in a particular procedure to LOCAL. The effect of 
this is that the variable only exists as an "anonymous" stack location; its 
name is compiled away and called routines cannot see it (i.e. they would 
have to use the name). Undeclared non-LOCAL variables are automatically 
declared FLUID by the compiler with a warning. In many cases, this means 
that a previous procedure that bound this variable should have known about 
this as a FLUID. Declare it with FLUID, below, and recompile, since the 
caller cannot be automatically fixed. 


[??? Should we provide an !*AllFluid flag to make the default Fluid, or 
should we make Interpreter have a LOCAL variable as default, or both 
227] 


ed 


ud 
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Fluid (NAMES:id-list): any expr 
Declares each variable FLUID (if not previously declared); this 
means that it can be used as a Prog LOCAL,.or as a parameter, - On 
entry to the procedure, its current value is saved on the Binding 
Stack (BSTACK), and all access is always to the VALUE cell 
(SYMVAL) of the variable; on exit (or Throw or Error), the old 
values are restored. 

Global (NAMES:id-list): any expr 


Declares each variable GLOBAL (if not previously declared); this 
means that it cannot be used as a LOCAL, or as a parameter. 
Access is always to the VALUE cell (SYMVAL) of the variable. 


[??2? Should we eliminate GLOBALs ???] 


19.2.7. Flags Controlling Compiler 
The compilation process is controlled by a number of flags, as well 
the above declarations and the !*COMP flag, of course. 


I*R2I (Initially: T) 


If T, causes recursion removal if possible, converting recursive 
calls on a function into a jump to its start. If this is not 
possible, it uses a faster call to its own "internal" entry, 
rather than going via the Symbol Table function cell. The effect 
in both cases is that tracing this function does not show the 
internal or eliminated recursive calls, nor the backtrace 
information. 


!*NOLINKE (Initially: NIL) 


If T, inhibits use of !*LINKE emacro. If NIL, "exit" calls on 
functions that would then immediately return. For example, the 
calls on FOO(x) and FEE(X) in 


PROCEDURE DUM(X,Y); 
IF X=Y THEN FOO(X) ELSE FEE(X+Y); 


can be converted into direct JUMP's to FEE or FOO's entry point. 
This is known as a "tail-recursive" call being converted to a 
jump. If this happens, there is no indication of the call of DUM 
on the backtrace stack if FEE or FOO cause an error. 


as 


flag 


flag 
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ORD (Initially: NIL) flag 


If T, forces the compiler to compile arguments in Left-Right 
Order, even though more optimal code can be generated. 


[??? !#ORD currently has a bug, and may not be fixed for some 
time. Thus do NOT depend on evaluation order in argument 
lists 777] 
!*MODULE (Initially: NIL) flag 
Indicates block compilation (a future extension of this 
compiler). When implemented, even more function and variable 


names are "compiled away". 
The following flags control the printing of information during the 
compilation process: 
!*PWRDS (Initially: NIL) flag 
If T, causes the compiled size to be printed in the form 
#%% NAME: base NNN, length MMM 
The base is in octal, the length is in current Radix. 


[?2?? more mnemonic name ???] 


!*PLAP (Initially: NIL) flag 


If T, causes the printing of the portable cmacros produced by the 
the compiler. 


Most of this information is printed by the resident LAP, and controlled 
by its flags, described below. 


19.2.8. Differences between Compiled and Interpreted Code 

The following just re-iterates some of the points made above and in other 
Sections of the manual regarding the "obscure" differences that compilation 
introduces. 


[?2?? This needs some careful work, and perhaps some effort to reduce 
the list of differences ???] 


In the process of compilation, many functions are open-coded, and hence 
cannot be redefined or traced in the compiled code. Such functions are 
noted to be OPEN-CODED in the manual. If called from compiled code, the 


roa 


eJ 
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call on an open-compiled function is replaced by a series of online 
instructions. Most of these functions have some sort of indicator on their 
property lists: 'OPEN, 'ANYREG, 'CMACRO, 'COMPFN, etc. For example: SETQ, 
CAR, CDR, COND, WPLUS2, MAP functions, PROG, PROGN, ate. Also note that 
some functions are defined as macros, which convert to some other form 
(such as PROG), which itself might compile open. 


Some optimizations are performed that cause inaccessible or redundant 
code to be removed, e.g. O#foo(x) could cause foo(x) not to be called. 


Unless variables are declared (or detected) to be Fluid or global, they 
are compiled as local variables. This causes their names to disappear, and 
so are not visible on the Binding Stack. Further more, these variables are 
NOT available to functions called in the dynamic scope of the function 
containing their binding. 


Since compiled calls on macros, fexprs and nexprs are different from the 
default exprs, these functions must be: declared (or defined) before 
compiling the code that uses them. While fexprs and nexprs may 
subsequently be redefined (as new functions of same type), macros are 
executed by the compiler to get the replacement, form, which is then 
compiled. The interpreter of course picks up the most recent definition of 
ANY function, and so functions can switch type as well as body. 


[??? If we expand macros at PUTD time, then this difference will go 
away. ???] 


As noted above, the !*R2I, !*NOLINKE and !¥*MODULE flags cause certain 
functions to call other functions (or themselves usually) by a faster route 
(JUMP or internal call). This means that the recursion or call may not be 
visible during tracing or backtrace. 


19.2.9. Compiler Errors 

A number of compiler errors are listed below with possible explanations 
of the error. 

*** Function form converted to APPLY 
This message indicates that the Car of a form is either 

a. Non-atomic, 


b. a local variable, or 
c. a global or fluid variable. 


The compiler converts (F X1 X2 ...), where F is one of the above, to (APPLY 
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F (LIST X1 X2 beads 
##% NAME already SYSLISP non-local 


This indicates that NAME is either a WVAR or WARRAY in SYSLISP mode, but is 
being used as a local variable in LISP mode. No special action is taken. 


*%% WVAR NAME used as local 


This indicates that NAME is a WVAR, but is being used as a bound variable 
in SYSLISP mode. The variable is treated as an an anonymous local variable 
within the scope of its binding. 


**% NAME already SYSLISP non-local 


This indicates that a variable was previously declared as a SYSLISP WVAR or 
WARRAY and is now being used as a LISP fluid or global. No special action 
is taken. 


*** NAME already LISP non-local 


This indicates that a variable was previously declared as a LISP fluid or 
global and is now being used as a SYSLISP WVAR or WARRAY. No special 
action is taken. 


*** Undefined symbol NAME in Syslisp, treated as WVAR 


A variable was encountered in SYSLISP mode which is not local nor a WVAR or 
WARRAY. The compiler declares it a WVAR. This is an error, all WVARs 


should be explicitly declared. 
*X*X* NAME declared fluid 


A variable was encountered in LISP mode which is not local nor a previously 
declared fluid or global. The compiler declares it fluid. This is 
sometimes an error, if the variable was used strictly locally in an earlier 
function definition, but was intended to be bound non-locally. All fluids 
should be declared before being used. 


19.3. The Loader 
[??? update ???] 


Currently, PSL on the DEC-20 provides a simple LISP assembler, LAP. This 
is modeled after the original LISP 1.6 LAP, although completely 
reimplemented to take advantage of PSL constructs, and to support the 
additional requirements of SYSLISP. In the process of implementing the VAX 
LAP and developing the LAP-to-ASM translator required to bootstrap PSL onto 
the next machine (Apollo MC68000), a much more table-driven form of LAP was 
designed to make all LAP's, LAP-to-ASM's and FASL's (fast loaders, 
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sometimes called FAP) easier to maintain. This is now in use on the VAX 
and being used to implement Apollo PSL. 


[2?? FASL now works ???] 


Until that is complete, we will briefly describe the available functions, 
and give a sample of current and future LAP; this Section will be 
completely rewritten in the next revision. LAP is currently a full two 
pass assembler; on the VAX and Apollo it also includes a pass to optimize 
long and short jumps. 


LAP (CODE:list): code-pointer expr 


CODE is a list of legal LAP forms, including: 


a. Machine specific Mnemonics (using opceode-names from the 
assembler on the DEC-20, VAX or Apollo). 


b. Compiler cmacros (which expand in a machine specific way). 
These can be thought of as "generic" or LISP-oriented 
instructions. See the next Section on the Compiler details, and 
list of legal cmacros. 


e. LAP pseudo instructions, to declare entry points, indicate data 
and constants, etc. 


The first pass of LAP converts mnemonics into LISP integers, doing as 
much of the assembly as possible, allocating labels and constants. The 
second (and third?) pass fills in labels and completes the assembly, 
depositing code into the next available locations in BPS, or creating FASL 
or LAP files. 


[??? What is BPS (binary program space) ???] 


19.3.1. Legal LAP Format and Pseudos 


[??? Describe LAP format in detail ???] 


19.3.2. Examples of LAP for DEC-20, VAX and Apollo 

The following is a piece of VAX specific LAP, using the current NEW 
format. Apart from the VAX mnemonics, notice the extra tags around the 
register names, and the symbols to indicate addressing modes (essentially 
PREFIX syntax rather then INFIX € etc.). This is from PV:APPLY-LAP,RED, 
Note they are almost ENTIRELY written in cmacros, to aid in re-coding for 
the next machine. 
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lap '((!*entry FastApply expr 0) 
%. Apply with arguments loaded 
% Called with arguments in the registers and functional form in t1 
(!*FIELD (reg t2) (reg t1) 
(WConst TagStartingBit) (WConst TagBitLength)) 
(1*FIELD (reg t1) (reg t1) 
(WConst InfStartingBit) (WConst InfBitLength)) 
(1 * JUMPNOTEQ (Label NotAnID) (reg t2) (WConst ID)) 
(1*WTIMES2 (reg t1) (WConst AddressingUnitsPerFunctionCell)) 
(1*JUMP (MEMORY (reg t1) (WArray SymFnc))) 
NotAnID 
(1 *JUMPNOTEQ (Label NotACodePointer) (reg t2) (WConst CODE)) 
(1*JUMP (MEMORY (reg t1) (WConst 0))) 
NotACodePointer 
(1* JUMPNOTEQ (Label IllegalFunctionalForm) (reg t2) (WConst PAIR)) . 
(!*MOVE (MEMORY (reg t1) (WConst 0)) (reg t2)) 
% CAR with pair already untagged 
(1*JUMPNOTEQ (Label IllegalFunctionalForm) (reg t2) (QUOTE LAMBDA)) 
(!*MOVE (reg t1) (reg t2)) % put lambda form in t2 
(!*PUSH (QUOTE NIL)) % align stack 
(1*JCALL FastLambdaApply) 
IllegalFunctionalForm 
(MOVE (QUOTE "Illegal functional form in Apply") (reg 1)) 
(!*MOVE (reg t1) (reg 2)) 
(!*CALL List2) 
(!¥JCALL StdError) 
IS 


lap '((!*entry UndefinedFunction expr 0) 
%. Error Handler for non code 
% Called by JSB 
$ 
(subl3 (immediate (plus2 (WArray SymFnc) 6)) 
(autoincrement (reg st)) 
(reg t1)) 
(divl2 6 (reg t1)) 
(!*MKITEM (reg t1) (WConst ID)) 
(1*MOVE (reg t1) (reg 2)) 
(!*MOVE (QUOTE "Undefined function fr called from compiled code") 
(reg 1)) 
(!*#CALL BldMsg) 
(!*JCALL StdError) 


The following is a piece of Apollo specific LAP, using the current NEW 
format. Apart from the MC68000 mnemonics, notice the extra tags around the 
register names, and the symbols to indicate addressing modes (essentially 
PREFIX. syntax rather then INFIX @ etc.). This is from P68:M68K-USEFUL- 
LAP.RED. i - 
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% Signed multiply of 32 bits numbers in A1 and Ae, 

% returns 64 bits in A1 and A2, low in 41 high in A2 

% Clobbers D1,D2,D3,D4,D5,D6,D7, no saving 

7 [Can insert MOVEM!.L D1-D7,-(SP) 

2 and MOVEM! ,L (SP)+,D1-D7] 

LAP '((!*entry Mult32 expr 2) % Arguments in Aji and A2 


(move!.1 (reg a1) (reg d1)) 

(move!.1 (reg a1) (reg d6)) 

(move!.1 (reg a2) (reg d2)) 

(move! .1 (reg a2) (reg d7)) % Need copies 

% Now do Unsigned Multiply 

(move! .1 (reg d1) (reg d3)) 

(move!.1 (reg d1) (reg d4)) 

(swap (reg d4)) 

(move!.1 (reg d2) (reg d5)) 


(swap (reg d5)) % Swapped for partial products 
(mulu!.w (reg d2) (reg d1)) % partial products (pp1) 
(mulu! .w (reg d4) (reg d2)) 4 pp2 
(mulu!.w (reg d5) (reg d3)) 4% pp3 
(mulu!.w (reg d5) (reg d4)) 4% pp4 
(swap (reg d1)) % sumi=pp#2low+pp# thi 
(add (reg d2) (reg d1)) 

(clr!.1 (reg d5)) 

(addx!.1 (reg d5) (reg d4)) % propagate carry 

(add (reg d3) (reg d1)) 4% sum2=sum1+pp#3low 
(addx!.1 (reg d5) (reg d4)) % carry inot pp#4 

(swap (reg d1)) % low order product 

(elr (reg d2)) 

(swap (reg d2)) 

(elr (reg d3)) 


(swap (reg d3)) 
(add!.1 (reg d3) (reg d2)) % Sum3=pp2low+pp3Hi 
(add!.1 (reg d4) (reg d2)) % Sum4=Sum3+pp4 

% Now do adjustment 


(tst!.1 (reg d7)) % Negative 

(bpl!.s chkd6) % nope 

(sub!.1 (reg d6) (reg d2)) % Flip 
chkd6 

(tst!.1 (reg d6)) % Negative 

(bpl!.s done) % nope 

(sub!.1 (reg d7) (reg d2)) % Flip 


done 
(movea!.1 (reg d1) (reg a1)) % low part 
(movea!.1 (reg d2) (reg a2)) % high part 
(rts)); 
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19.3.3. Lap Flags 
The following flags control the printing of information from LAP and 
other optional behavior of LAP: 

!*PLAP (Initially: NIL) flag 
Causes LAP forms to printed before expansion. Used mainly to see 
output of compiler before assembly. z 

!*PGWD (Initially: NIL) flag 
Causes LAP to print the actual DEC-20 mnemonics and corresponding 
assembled instruction in octal, displaying OPCODE, REGISTER, 
INDIRECT, INDEX and ADDRESS fields. 

I*PWRDS (Initially: T) flag 
Prints a LAP message of the form 


**X% NAME: base NNN, length MMM 


The base is in octal, the length is in current Radix. 


!*SAVECOM (Initially: T) flag 
If T, the LAP is deposited in BPS, and the returned Code-Pointer 
used to (re)define the procedure associated with the (!*entry 
name type n). 

!*SAVEDEF (Initially: NIL) flag 
If T, and if !*SAVECOM is T, saves any preexisting procedure 
definition under '!*SAVEDEF on the property list of the procedure 
name, "just in case", 

LAP also uses the following indicators on property lists: 
"MC Cmacros and some mnemonics have associated PASS1 expansions in 


terms of simpler instructions or operations. The form (me al ... 
an) has its associated function applied to (al ... an). 


For more details, see "P20:LAP,RED", 
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19.4. Structure and Customization of the Compiler 


The following is a brief summary of the compiler structure and model. 
The purpose of this Section is to aid the user to add new ‘compilation 
forms, and to understand the task of bootstrapping a new version of PSL. 
The original paper on the Portable LISP Compiler [Griss 81] has complete 
details on the original version of the compiler, and should be read in 
eonjunetion with this Section. It might be useful to also examine the 
paper on recent work on the compiler [Griss82], 


[??? This needs a LOT of work ???] 


The compiler is basically three-pass: 


a. The first pass expands ordinary macros, and compiler specific 
emacros. It also uses some special purpose '‘'PA1REFORM and 
'PAIFN functions on the property lists of certain functions to 
produce a Simpler and more explicit LISP for the next pass. 
Variables and constants, x, are explicitly tagged as (FLUID x), 
(GLOBAL x), (QUOTE x), (WCONST x), etc. 


b. The second pass recursively compiles the code, using 'COMPFN's 
to handle special cases, and the recursive function !&COMPILE 
for the general case. In general, code is compiled to cause 
function arguments to be loaded into R1...Rn in order, a CALL to 
the function to be made, and the returned value to appear in R1. 
Temporaries and function arguments to be reused later are saved 
on the stack. The compiler allocates a single FRAME for the 
maximum stack space that might be needed, and then trims it down 
in the third pass. PSL requires registers R1 ... R15, though 
not all need be "REAL registers"; the extra are simulated as 
memory locations. Special cases avoid a lot of LOAD/STORES to 
move arguments around. The compiled code is emitted as a 
sequence of abstract LISP machine cmacros. The current set of 
emacros is described below. 


C. The third pass scans the list of cmacros for patterns, removing 
LOADs and STOREs, redundant JUMP's and LABEL's, compressings the 
Stack frame, and possibly mapping temporaries stored on the 
stack into any of the REAL registers that would otherwise be 
unused. This optimized cmacro list is then passed to LAP. 


19.5. First PASS of Compiler 
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- 19.5.1. Tagging Information 

This affects many parts of the compiler. The basic idea is that all 
information is to be tagged. These tags fit in three categories: variable 
tags, location (register and frame) tags, and constant tags. Tags used for 
variables must be flagged 'VAR; tags for constants must be flagged 'CONST. 
Currently, the register tag is REG and the frame tag is FRAME. Frame 
locations are always positive integers. 


These tags are used everywhere; thus, register 1 is always described by 
(REG 1) in both emitted cmacros and internally in the register list REGS. 
Pass 1 tags all variable references with a source to source transformation 
of the variables (suitably obscure names must be used for these tags to 
prevent conflicts with named functions). 


The purpose behind this tagging is to make the compiler easier to work 
with in adding new features; new notions of registers, constants, and 
variables can all be accommodated through new tags. Also, the components 
of the cmacros are more clearly identified for pass 3. 


19.5.2. Source to Source Transformations ; 

, A PA1TREFORMFN has been provided to augment PAIFN's. The only difference 
between these functions is that the PATREFORM function is passed code which 
has already been through PASS1. This was previously done by calling pass 1 
within a PAIFN. 


19.6. Second PASS - Basic Code Generation 


19.6.1. The Cmacros 

The compiler second pass compiles the input LISP into a series of 
abstract machine instructions, called cmacros. These are instructions for 
a LISP-oriented Register machine. 


The current DEC-20 cmacros 
Definitions of arguments 


reg: (REG n) n = 1,2,... MAXNARGS 


var: frame | (GLOBAL name) | (FLUID name) 
frame: (FRAME n) =D We ee 


const: (QUOTE value) | (WCONST value) 
label: (LABEL symbol) 

regn: reg i NIL | frame 

regf: reg ¡ frame 

loc: reg ¡ var ¡ const 

anyreg: (CAR anyreg) | (CDR anyreg). | loc 
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Basic Cmacros for LISP and SYSLISP 


(IALLOC nframe) 
(!#DEALLOC nframe) 
(I*ENTRY fname ftype nargs) 
(1*EXIT nframe) 
(1*FREERSTR (NONLOCALVARS f1 f2 ...)) 
(!*#JUMP label) 
(1*JUMPxx label loc loc') 
where xx = ATOM, EQ, NOTEQ, NOTTYPE, PAIRP, TYPE 
(1*JUMPON lower upper (label-1 ... Label-n)) 
(!*LINK fname ftype nargs) 
(!*LINKE nframe fn type nargs) 
(!*LINKF nargs reg) where reg contains the function name, 
nargs an integer 
(!*LINKEF nframe nargs reg) %/ ? 
(!*LBL label) 
(!*LAMBIND (REGISTERS reg1 reg2 ...) (NONLOCALVARS f1 f2 ...)) 
where -f1, f2, ... = (FLUID name ) 
No frame location will be allocated (depends on flag) 
(!*LOAD reg anyreg) 
(!*PROGBIND (NONLOCALVARS f1 f2 ...)) 
(!*PUSH reg) 
(1*RPLACA regf loc) 
(!*RPLACD regf loc) 
(!*STORE regn var) ¡ (!*STORE regn reg) 


SYSLISP oriented Cmacros 


(1*ADDMEM loc) 

(!*ADJSP ?) 

(!*®DECMEM loc) 

(!*INCMEM loc) 

(!*INTINF loc) 

(!*JUMPWGEQ label loc loc') 
(!*JUMPWGREATERP label loc loc') 
(!*JUMPWITHIN label loc loc') 
(!*JUMPWLEQ label loc loc!) 
(1* JUMPWLESSP label loc loc') 
(!*MKITEM loc loc') 

(!*MPYMEM loc loc!) 

(!*NEGMEM loc) 

(1 *SUBMEM loc loc') 

(!*#WAND loc loc') 
(!*WDIFFERENCE loc loc') 
(!*WMINUS loc) 

(!*WNOT loc) 

(!*WOR loc loc') 

(1*WPLUS2 loc loc') 

(!*WSHIFT loc loc?) 
(!*WTIMES2 loc loc') 

(!#WXOR loc loc!) 
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68000 Cmacros 
Basic LISP and SYSLISP Cmacros 


(!*ALLOC nframe) 

(CALL fname) 

(!*DEALLOC nframe) 

(!*ENTRY fname ftype nargs) 
(EXIT nframe) 

(!*JCALL fname) 

(!*JUMP label) 

(!*JUMPEQ label loc loc') 
(!*JUMPINTYPE label type) 
(!*JUMPNOTEQ label loc loc') 
(!*#JUMPNOTINTYPE label loc type) 
(1*JUMPNOTTYPE label loc type) 
(!*JUMPTYPE label loc type) 
(!*LAMBIND label loc loc') 
(!*LBL label) 

(!*LINK fname ftype nargs) 
(!*LINKE fname ftype nargs nframe) 
(!¥MOVE loc loc') 

(!*PROGBIND label loc loc') 
(!*PUSH loc) 


SYSLISP specific Cmacros 


(!*¥APOLLOCALL label loc loc') 
(1*ASHIFT loc loc') 
(!*FIELD loc loc!) 
(!*FOREIGNLINK loc loc') 
(!*INF loc loc') 
(t*JUMPON loc loc!) 
(!*#JUMPWGEQ loc loc') 
(!*JUMPWGREATERP loc loc!) 
(!*JUMPWITHIN loc loc?!) 
(!* JUMPWLEQ loc loc') 

(1 * JUMPWLESSP loc loc!) 
(LOC loc loc!) 
(!*MKITEM loc loc!) 
(!*PUTFIELD loc loc’) 
(!*PUTINF loc loc!) 
(!*PUTTAG loc loc’) 
(!*SIGNEDFIELD loe loc') 
(!*TAG loc loc') 

(!*WAND loc loc!) 
(!*WDIFFERENCE loc loc?) 
(!*WMINUS loc loc!) 
(!*WNOT loc loc') 

(!*WOR loc loe') 
(IWPLUS2 loc loc!) 
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(1*WHSHIFT loc loc!) 
(!¥WTIMES2 loc loc!) 
(!*¥WXOR loc loc!) 


19.6.2. Classes of Functions 
The compiler groups functions into four basic classes: 


and Loader 
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a. ANYREG functions. No side effects and can be done in a single 
register. Passed directly to CMACROs. Viewed as a form of 


"extended addressing" mode. 


b. Specially compiled or "OPEN" functions. These are functions 
have a special compiling function stored under a  'COMPEFN 
indicator. While many of these functions are specially coded, 


many are written with the aid of supporting patterns; these 


are 


called 'OPENFN or 'OPENTST patterns. Some OPEN functions alter 
registers which are in use, allocate new frames or obtain unused 
registers. These open functions also include open compilation 


of tests. 


c. Built-in or 'stable' functions. These functions are called in 
the standard fashion by the compiler, but they have properties 
which are useful to the compiler and are assumed to always hold. 


Currently, a function may be flagged as NOSIDEEFFECT and 


have 


the property DESTROYS, which contains a list of registers 


destroyed by the function. 


d. All other functions are assumed to be totally random, destroying 


every register and causing side effects. 


[??? Mark non-random functions of various levels elsewhere ???] 


The most important of these categories is the OPEN function. It is hoped 


that improved OPEN functions will eliminate the need for 


temporary 


registers to be allocated by the assembler. Most OPEN functions emit 


emacros especially tailored for each function. 


19.6.3. Open Functions 
[??? Explain how to CODE them ???] 


There are 3 basic kinds of open function: 


a. Test: the destination is a LABEL. 
b. Value: the result is to be placed in a particular register. 
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c. Effect: the result is a side effect, and no destination is 
needed. 
Note that an EFFECT open function does not have a destination. It is not 
really a separate class of function, just a separate usage. Example: 
(PROGN (SETQ X 0) ... ) 
- the SETQ is for effect only - could be implemented with a "clear" 


instruction. 


(FOO (SETQ X 0) ... ) 
- here the 0 is also placed in a register (the destination register). 


The use of OPENTST is also derived from context: in 
(COND ((EQ A B) ...)) 
-,EQ is interpreted as a test. 
(RETURN (EQ A B)) 


, though, must have a value. It should be noted that a pseudo 
source-source transformation occurs if an OPENTST is called for value: 


(RETURN (EQ A B)) -> 
(RETURN (COND ((EQ A B) T) (T NIL))) 


An OPENTST function always returns T/NIL if called for value. No separate 
handling for non test cases is needed (as opposed to the effect/value cases 
for normal OPEN funs in which two separate expansions can be supplied) 


Also, there are 3 basic issues encountered in generating the code: 


a. Bringing arguments into registers as needed. 
b. Emitting the actual code. 
C. Updating the final register contents. 


Initially, the arguments to an open function are removed of all but 
ANYREG functions. Thus, these arguments fall into four classes: 


a. Registers 
b. Memory locations (FLUID, GLOBAL, FRAME, !*MEMORY) 


TE) 
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e. Constants 
d. ANYREG functions (viewed as extended addressing modes) 


Also, along with the arguments coming in is the destination (register or 
label). 


The first step is to replace some arguments by registers by emitting 
LOAD's. This step can be controlled by a function, called the adjust 
function, which emits LOAD's and replaces the corresponding arguments by 
registers. Next, cmacros are emitted. These cmacros are selected through 
a pattern which defines the format of the particular OPEN function call. 


Note that the pattern is matching the locations of the arguments to the 
open function. For example, assume that FOO is OPEN, and the call 


(FOO 'A (CDR B) C D) 


is encountered. Assume also that B is frame 1, C is frame 2, and D was 
found in reg 1. 


The argument list being matched is thus 
('A (CDR (FRAME 1)) (FRAME 2) (REG 1)) 


For most purposes, this would be interpreted as (const anyreg mem reg). Of 
course, a pattern can use the value of a constant (you might recognize 
(!®WPLUS2 1 X) as an increment). Also, the actual register may be 
important for register args, especially if one of the args is also the 
destination. You would probably emit different code for 


(REG 1) := (!*WPLUS2 (REG 2) (REG 3)) 
than 
(REG 1) := (!*WPLUS2 (REG 1) (REG 2)) 

To avoid a profusion of properties which would be associated with an OPEN 
function, two properties of the function name are used to hold all 
information associated with OPEN compiling. These properties are OPENFN 
and OPENTST. 

The OPENFN and OPENTST properties have the following format: 


(PATTERN MACRONAME PARAMETERS) 
or function name. 
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The PATTERN field contains either the pattern itself or a pattern name. 
A pattern name is an id having the PATTERN property. In the following 
material, DEST refers to. the destination label in an OPENTST and to the 
destination register in an OPENFN. If the function is being evaluated for 
effect only, DEST is a temporary register which need not be used. 


A pattern has the following format: 


(ADJUST FN 
REG FN 
(P1 M11 M12 M13 ..) 
(P2 M21 M22 M23 ..) 
et) 


The Pi are patterns and Mij are cmacros or pseudo emacros. ADJUST FN is a 
register adjustment function used to place things in registers as required, : 
and to factor out basic properties of the function from the pattern. For 
example, you almost never could do anything with ANYREG stuff except load 
it somewhere (emitting (!*WPLUS2 X (CDR (CAR Y))) directly probably won't 
work -= you must bring (CDR (CAR Y)) into a reg before further progress can 
be made). The most common adjust function is NOANYREG, which replaces 
ANYREG stuff with registers. This eliminates the problem of having to test 
for ANYREG stuff in the patterns. 


Some pattern elements currently supported are: 


ANY matches anything 

DEST matches the destination register or label 

NOTDEST matches any register except the destination 

REG matches any register 

REGN Any register or 'NIL or a frame location 

VAR A LOCAL, GLOBAL, or FLUID variable 

MEM A memory address, currently constants + vars (NOT REGS) 


ANYREGFN matches an ANYREG function 
‘literal matches the literal 
(pi p2 ... pn) 
matches a field whose components match p1 ... pn 
NOVAL matches only if STATUS > 1; must be the first component of a 


pattern, consumes no part of the subject. 


The cmacros associated with the patterns fall into two classes: actual 
emacros to be emitted and pseudo cmacros which are interpreted by the 
compiler. In either case, the components of the cmacros are handled in the 
same fashion. The cmacros contain: 


Ai replaced by the ith argument to the OPEN function (after 
adjustment) 


ud 
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Ti replaced by a temporary register 
Li replaced by a temporary label 
Pi replaced by corresponding parameter from OPENFN 
DEST replaced by the destination register or label (depending on 
OPENFN or OPENTST). 
FN replaced by the name of the OPEN function 
MAC synonym for P1, by convention a cmacro name 
‘literal 
(x1 X2 ... ) 
xi as above, forms a list 
The pseudo cmacros currently supported are: 
I*DESTROY (R1, R2, ...): list cmacro 
Remove any register values from R1 ... RN. 
1*DO (FUNCTION ARG1 ARG2 ...): list cmacro 
Call the FUNCTION. 
!®SET (REG VAL): list < emacro 
Set the value in REG to VAL. 
The cmacros which are known to the compiler are 
I*LOAD (): list emacro 
t*STORE (): list cmacro 
JUMP (): list emacro 
1*LBL (): list cmacro 
These cmacros have special emit functions which are called as they are 


emitted; otherwise the cmacro is directly attached to CODELIST. 
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19.7. Third PASS - Optimizations 


The third pass of the compiler is responsible for doing optimizations, 
getting rid of extra labels and jumps, removing redundant code, adjusting 
the stack frame to squeeze out "holes" or even reallocating temporaries to 
excess registers if no "random" functions are called by this function. 


This pass also does "peephole" optimizations (controlled by patterns that 
examine the Output CMACRO list for cmacros that can be merged). These 
tables can be adjusted by the user. This pass also gathers information on 
register usage that may be accumulated to aid block compilation or 
recompilation of a set of functions that are NOT redefined, and so can use 
information about each other (i.e. become "stable"), 


The 'OPTFN property is used to associate an optimization function with a 
particular CMACRO name. This function looks at the CMACRO arguments and 
some subsequent CMACROs in the code-list, to see if a transformation is 
possible. The OPTFN takes a Single argument, the code-list in reverse 
order starting at the associated CMACRO. The OPTFN can also examine 
certain parameters. Currently !*LBL, !*MOVE and !*JUMP have 'OPTFNS. For 
example, !&STOPT, associated with !*MOVE, checks if previous CMACRO was 
!¥ALLOC, and that this !*MOVE moves a register to the slot just allocated. 
If so, it converts the !*ALLOC and !*MOVE into a single !*PUSH. Likewise, 
!&LBLOPT removes duplicate labels defined at one place, aliasing one with 
the other, and so permitting certain JUMP optimizations to take place, 


Tags in the cmacros are processed in a final pass through the code. At 
this time the compiler can do substitutions using functions attached to 
these tags. Currently, (!*FRAMESIZE) is converted to the frame size and 
holes are squeezed out (using the FRAME tag) by !&REFORMMACROS. 
Transformation functions are attached to tags (or any function) through the 
TRANFN property currently. 


19.8. Some Structural Notes on the Compiler 


[??? This Section is very ROUGH, just to give some additional 
information in interim ???] 


External variables and properties used by the compiler: 


Variables and Flags 


a 
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I#ERFG (Initially: ) flag 
PET NS TALLDESTROY (Initially: NIL) flag 


If true, causes the compiler to install the DESTROYS property on 
any function compiled which leaves one or more registers 


unchanged 
I*INT (Initially: T) flag 
!¥NOFRAMEFLUID (Initially: T) . flag 


If true, inhibits allocation of frame locations for FLUIDS 


I*SHOWDEST (Initially: NIL) flag 
If true, compiler prints out which registers a function destroys 
unless all are destroyed 

!*SYSLISP (Initially: NIL) flag 
Switch compilation mode from default of LISP to SYSLISP. This 
affects constant tagging, and in RLISP also causes LISP functions 
to be replaced by SYSLISP equivalents. Also, non-locals default 
to WVAR's rather than FLUIDS. See Chapter 21. 

!*UNSAFEBINDER (Initially: NIL) | | flag 
for Don's BAKER problem...GC may be called in Binder, so regs 
cannot be preserved, and Binder called as regular function. 


!*USEREGFLUID (Initially: NIL) flag 


If true, LAMBIND and PROGBIND cmacros: may contain registers as 
well as frame locations (through FIXFRM). 


Globals: 


LASTACTUALREG (Initially: 5) global 


The number of the last real register; FIXFRM does not map stack 


locations into registers > LASTACTUALREG. Also, temporary 
registers are actual registers if possible. 
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MAXNARGS (Initially: 15) global 


Number of registers 


Properties and Flags: 


CONST A tag property, indicates tags for constants (WCONST and QUOTE) 

EXTVAR A tag property, indicates a variable type whose name is 
externally known (!$FLUID, !$GLOBAL, !$WVAR) 

MEMMOD A cmacro property, indicates in place memory operations. The 
first argument to the cmacro is assumed to be the memory location 
(var or !*MEMORY) 

NOSIDEEFFECT 
A function property, used both in dealing with !*ORD and to 
determine if the result should be placed in register status 

REG A tag property, indicates a register (REG) 

TERMINAL A tag property, indicates terminals (leaves) whose arguments are 
not tagged items (!$FLUID !$GLOBAL !$WVAR REG LABEL QUOTE WCONST 
FRAME !*FRAMESIZE IREG) 

TRANSFER A property of cmacros and functions, indicates cmacros & 
functions which cause unconditional transfers (!*JUMP !*EXIT 
!*LINKE !*LINKEF ERROR) 

VAR A tag property, indicates a variable type (!$LOCAL !$FLUID 


¡$GLOBAL !$WVAR) 


Properties: 


. ANYREG 
CFNTYPE 
DESTROYS 
DOFN 


EMITFN 


EXITING 


FLIPTST 


GROUPOPS 


MATCHFN 


NEGJMP 


A function property, non-NIL indicates an ANYREG function 

Used in compiler to relate to Recursion-to-iteration conversion. 
A function property, contains a (tagged) list of registers 
destroyed by the function 

A function property, contains the name of a compile time 
evaluation function for numeric arguments. 

A emacro or pseudo cmacro property, contains the name of a 
special function for emitting (or executing) the cmacro, such as 
I&ATTJMP for !*JUMP. l 

A cmacro property, used in FIXLINKS. Contains the name of an 
associated exiting cmacro (!*LINK : !*LINKE, !*LINKF : !*LINKEF) 
A function property, contains the name of the opposite of a test 
function. All open compiled test functions must have one. (EQ: 
NOTEQ, ATOM : PAIRP) 

A function property, used in constant folding. Attached to the 
three functions of a group, always a list of the three functions 
in the order +, -, MINUS. (!*WPLUS2, !*WDIFFERENCE, !*WMINUS : 
(!*WPLUS2 !*WDIFFERENCE ! *WMINUS) ) 

A property attached to an atom in a pattern. Contains the name 
of a boolean function for use in pattern matching. 

A cmacro property, contains the inverted test jump cmacro name. 
(!#JUMPEQ : !*JUMPNOTEQ, !*JUMPNOTEQ : !*JUMPEQ ...) 


L 


J 


J 
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ONE A function property, contains the (numeric) value of an identity 
associated with the function (!*WPLUS2 : 0, !*WTIMES2 : 1, ...) 

PATTERN A property associated with atoms appearing in OPENFN or OPENTST 
properties, contains a pattern for open coding of functions. 

SUBSTFN A property of atoms found in cmacros which are inside patterns. 
Contains a function name; the function value is substituted into 
the cmacro as emitted. 

ZERO Like ONE, designates a value which acts as a 0 in a ring over *, 


(1*YTIMES2 : 0 , !*LOGAND : 0) 


J 
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CHAPTER 20 
OPERATING SYSTEM INTERFACE 


20.1. Introduction 20.1 
20.2. System Dependent Functions 20.1 
20.3. TOPS-20 Interface 20.2 
20.3.1. User Level Interface 20.2 
20.3.2. The Basic Fork Manipulation Functions 20.4 
20.3.3. File Manipulation Functions 20.5 
20.3.4. Miscellaneous Functions 20.6 
20.3.5. Jsys Interface 20.6 
20.3.6. Bit, Word and Address Operations for Jsys Calls 20.8 
20.3.7. Examples 20.9 


20.1. Introduction 


From within each PSL implementation, there will be a set of functions 


“that permit the user to access specific operating system services. On the 


DEC~20 and VAX these include the ability to submit commands to be run in a 
"lower fork", such as starting an editor, submitting a system print 
command, listing directories, and so on. We will attempt to provide such 
calls (EXEC and CMDS) in all PSL implementations. We also will provide as 
clean an interface to Low-level services as possible. On the DEC-20, this 
is the Jsys function. Appropriate support functions (such as bit 
operations, byte-pointers, etc.) are also used by the assembler. On the 
VAX we will provide the SYSCALL capability. 


20.2. System Dependent Functions 


If System (SYS-NAME:id, TRUE-CASE:any, FALSE-CASEsany): any cmacro 


This is a compile-time conditional macro for system-dependent 
code. FALSE-CASE can be omitted and defaults to NIL. SYS-NAME 
must be a member of the fluid variable System_List!*. For the 
Dec-20, System List!* is (Dec20 PDP10 Tops20 KL10). For the VAX 
it is (VAX Unix VMUnix). An example of its use follows. 


PROCEDURE MAIL(); 
IF_SYSTEM(TOPS20, RUNFORK "SYS:MM.EXE", 
IF_SYSTEM(UNIX, SYSTEM "/BIN/MAIL", 
STDERROR "MAIL COMMAND NOT IMPLEMENTED") ); 
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20.3. TOPS-20 Interface 


20.3.1. User Level Interface f . 

The basic funetion of interest is DoCmds, which takes a list of strings 
as arguments, concatenates them together, starts a lower fork, and submits 
this string (via the Rescan buffer). The string should include appropriate 
<CR><LF>, "POP" etc. A global variable, CRLF, is provided with the 
<CR><LF> string. Some additional entry points, and common calls have been 
defined to simplify the task of submitting these commands. 


DoCmds (L:string-list): any expr 
Concatenate strings into a single string (using ConcatS), place 
into the rescan buffer using PutRescan, and then run a lower 
EXEC, trying to use an existing Exec fork if possible. 

CRLF (Initially: "<er><lf>") global 
This variable is "CR=-LF", to be appended to or inserted in 
Command strings for fne(DoCmds). It is STRING(Char CR,Char LF). 

ConcatS (L:string-list): string expr 
Concatenate string-list into a single string, ending with CRLF. 

[2?? Probably ConeatS should be in STRING, we add final CRLF in 
PutRescan ???] 
Cmds ([L:string]): any fexpr 


Submit a set of commands to lower EXEC 


E.g. CMDS("VDIR *.RED ", CRLF, "DEL *.LPT", CRLF, "POP");. 


The following useful commands are defined: 


VDir (L:string): any expr 


Display a directory and return to PSL, e.g. (VDIR "R.*"). 
Defined as DoCmds LIST("VDIR ",L,CRLF,"POP"); 
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Display PSL help directory. Defined as DoCmds LIST("DIR 
PH: *,.HLP",CRLF,"POP"™). 
sys (L:string): any expr 


Defined as DoCmds LIST("SYS ", L, CRLF, "POP"); 


Take (L:list): any expr 


Defined as DoCmds LIST("Take ",FileName,CRLF,"POP"); 


Type (L:string): any expr 
Type out files. Defined as DoCmds LIST("TYPE ",L,CRLF,"POP"); 

While definable in terms of the above DoCmds via a string, more direct 

execution of files and fork manipulation is provided by the following 


functions. Recall that file names are simply Strings, e.g. "<psl>foo.exe", 
and that ForkHandles are allocated by TOPS-20 as large integers. 


Run (FILENAME:string): any expr 
Create a fork, into which file name will be loaded, then run it, 
waiting for completion. Finally Kill the fork. 

Exee (): any expr 
Continue a lower EXEC, return with POP. The Fork will be created 
the first time this is run, and the ForkHandle preserved in the 
global variable ExecFork. 

Emacs (): any expr 
Continue a lower EMACS fork. The Fork will be created the first 


time this is run, and the ForkHandle preserved in the global 
variable EmacsFork. 


[??? Figure out how to pass a buffer to from Emacs ??7] 
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MM (): any | | expr 
Continue a lower MM fork. The Fork will be created the first 
time this is run, and the ForkHandle preserved in the global 
variable MMFork. i 
??? MM looks in the rescan buffer for commands, so fairly 
useful mailers (e.g. for BUG reports) can be created. 
Perhaps make MM(s:string) for this purpose. ???] 


Reset (): None Returned expr 


This function causes the system to be restarted. 
20.3.2. The Basic Fork Manipulation Functions 


GetFork (JFN:integer): integer | expr 


Create a fork handle for a file; a GET on the file is done. 


StartFork (FH:integer): None Returned. expr 
Start a fork running, don't wait, do something else. Can also be 
used to Restart a fork, after a WaitFork. 

WaitFork (FH:integer): Unknown expr 


Wait for a running fork to terminate. 


RunFork (FH:integer): Unknown expr 


Start and Wait for a FORK to terminate. 


KillFork (FH:integer): Unknown expr 


Kill a fork (may not be restarted). 


OpenFork (FILENAME:string): integer expr 


Get a file into a Fork, ready to be run. 
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PutRescan (S:string): Unknown expr 
Copy a string into the rescan buffer, and announce to system, so 
that next PBIN will get this characters. Used to pass command 
strings to lower forks. 

GetResean (): {NIL,string} expr 
See if there is a string in the rescan buffer. If not, Return 
NIL, else extract tnat string and return it. This is useful for 
getting command line arguments in PSL, if MAIN() is rewritten by 


the user. This will also include the program name, under which 
this is called. 


20.3.3. File Manipulation Functions 
These mostly return a JFN, as a small integer. 


GetOldJfn (FILENAME:string): integer expr 


Get a Jfn on an existing file. 


GetNewJfn (FILENAME:string): «integer expr 


Get a Jfn for an new (non-existing) file. 


Reldfn (JFN:integer): integer expr 


Return Jfn to TOPS-20 for re-use. 


FileP (FILENAME:string): boolean expr 
Check if FILENAME is existing file; this is a more efficient 
method than the Kernel version that uses ErrorSet. 

OpenOldJfn (JFN:integer): integer expr 


Open file on Jfn to READ 7-bit bytes. 


OpenNewdfn (JFN:integer): Unknown expr 


Open file on Jfn to write 7 bit bytes. 
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GtJfn (FILENAME:string,BITS:integer): integer expr 


Get a Jfn for a file, with standard Toos-20 Access bits set. 


NameFromJfn (JFNsinteger): string expr 


Find the name of the File attached to the Jfn. 
20.3.4. Miscellaneous Functions 


GetUName (): string expr 


Get USER name as a string 


GetCDir (): string expr 


Get Connected DIRECTORY 


InFile (LFILS:id-list]): Unknown fexpr 


Either solicit user for file name (InFile), and then open that 
file, else open specified file, for input. 


20.3.5. Jsys Interface 
The Jsys interface and jsys-names (as symbols of the form jsXXX) are 
defined in the source file PU:JSYSO.RED. 


The access to the Jsys call is modeled after IDapply to avoid CONS, 
register reloads. These could easily be done Open coded 


The following SYSLISP calls, XJsys'n', expect W-values in the registers, 
Rl...R4, a W-value for the Jsys number, Jnum and the contents of the ‘nth! 
register. Unused registers should be given 0. Any errors detected will 
result in the JsysError being called, which will use the system ErStr JSYS 
to find the error string, and issue a StdError. 


XJsys0 (Ri:s-integer, R2:s-integer, R3:s-integer, 
R4:s-integer, Jnum:s-integer): s-integer expr 


Used if no result register is needed. 
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R4:s-integer, Jnum:s-integer): s-integer expr 


R4ss-integer, Jnum:s-integer): s-integer expr 


R4:s-integer, Jnum:s-integer): s-integer expr 


XJsys4 (Rl:s-integer, R2:s-integer, R3:s-integer, 
R4ss-integer, Jnum:s-integer): s-integer expr 


The following functions are the LISP level calls, and expect integers or 
strings for the arguments, which are converted into s-integers by the 
function JConv, below. We will use JS to indicate the argument type. The 
result returned is an integer, which should be converted to appropriate 
type by the user, depending on the nature of the Jsys. See the examples 
below for clarification. 


JsysO (R1:JS, R2:JS, R3:JS, R4:JS, Jnum:s-integer): integer expr 


sed is no result register is needed. 


Jsysi (R1:JS, R2:JS, R3:JS, R4:JS, Jnum:s-integer): integer expr 
Jsys2 (R1:JS, R2:JS, R3:JS, R4:JS, Jnum:s-integer): integer expr 
Jsys3 (R1:JS, R2:JS, R3:JS, R4:JS, Jnum:s-integer): integer expr 
Jsys4 (R1:JS, R2:JS, R3:JS, R4:JS, Jnum:s-integer): integer expr 


The JConv converts the argument type, JS, to an appropriate s-integer, 
representing either an integer, or string pointer, or address. 


JConv (J:finteger,string)): s-integer expr 


An integer J is directly converted to a s-integer, by Int2Sys(J). 
A string J is converted to a byte pointer by the call 
Lor( 8#10700000000,Strinf(J)). Otherwise a StdError, "'J' not 
known in Jconv" is produced. 


Additional convertions of interest may be performed by the functions 
Int2Sys, Sys2Int, and the following functions: 
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Str2Int (S:string): integer 
Returns tne physical address of the string start as an integer; 
this can CHANGE if a GC takes place, so snould be done just 
before calling the jsys. 

Int2Str (J:integer): string 


J is assumed to be the address of a string, and a legal, tagged 
string is created. 


20.3.6. Bit, Word and Address Operations for Jsys Calls 


RecopyStringToNULL (S:w-string): string 


S is assumed to be the address of a string, and a legal, tagged 
string is created, by searching for the terminating NULL, 
allocating a HEAP string, and copying the characters into it. 
This is used to ensure that addresses not in the LISP heap are 
not passed around "“cavalierly" (although PSL is designed to 
permit this quite safely). 


Swap (X:integer): integer 
Swap half words of X; actually Xword(LowHalfWord X,HighHalfWord 
X). 


LowHalfWord (X:integer): integer 


Return the low-half word of the machine representation of 
X. Actually Land(X, 8#777777). 


HighHalfWord (X:integer): integer 


Return the Upper half word as a small integer, of the machine 
word representation of X. Actually 
Lsh(Land(X, 8#777777000000) ,-18). 


Xword (X:integer,Y:integer): integer 


Build a Word from Half-Words, actually 
Lor(Lsh(LowHalfWord(X),18),LowHalfWord Y). 


20.3 


expr 


expr 


expr 


expr 


expr 


expr 


expr 
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JBits (L:list): integer 


Construct 


byte-rields. 
integer in 


word-image by OQOR'ing together selected bits or 
L is list of integers or integer pairs. A Single 
the range 0...35, BitPos, represents a single bit to 


be turned on. A pair of integers, (FieldValue . RightBitPos), 


causes the 
Significant 
This value 
DEC-20, the 
is bit 35. 


integer FieldValue to be shifted so its least 
bit (LSB) will fall in the position, RightBitPos. 
is then OR'ted into the result. Recall that on the 
most significant bit (MSB), is bit O and that the LSB 


Bits (L:list): integer 


A convenient access to Jbits: JBits cdr L. 


20.3.7. Examples 
The following 


range of examples illustrate the use of the 


functions. More examples can be found in PU:sexecO.red. 


Jsys1(0,0,0,0,jsPBIN); 
% Reads a character, returns the ASCII code. 


Jsys0(ch,0,0,0,jsPBOUT); 
% Takes ch as Ascii code, and prints it out. 


Procedure OPENOLDJfn Jfn; pe OPEN to READ 


JSYSO(Jfn,Bits( 


(7 . 5),19),0,0,jsOPENF); 


Lisp procedure GetFork Jfn; $. Create Fork, READ File on Jfn 
Begin scalar FH; 
FH := JSYS1(Bits(1),0,0,0,jsCFork); 
JSYSO(Xword(FH ,Jfn),0,0,0, jsGet); 


return FH 
END; 


Procedure GetOLDJfn FileName; %. test If file OLD and return Jfn 
Begin scalar Jfn; 
If NULL StringP FileName then return NIL; 
Jfn := JSYS1(Bits(2,3,17),FileName ,0,0, jsGTJfn) ; 
% OLD!MSG! SHORT 
If Jfn<0 then return NIL; 


return Jfn 
END; 


Procedure GetUNAME; 4. USER name 


Begin Scalar S; 


S:=Mkstring 30; % Allocate a 80 char buffer 


rface 
20.9 


expr 


macro 


above 
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JSYSO(s,JSYS1(0,0,0,0,jsGJINF),0,0, jsDIRST); 
Return RecopyStringToNULL S; 

% Since a NULL may be appear before end 

End; : . 


Procedure ReadTTY; 

Begin Scalar S; | 
S:=MkString(30); % Allocate a String Buffer 
Jsys0(S,BITS(10,(30 . 35),"Retype it1",0,jsRDTTY); 

% Sets a length halt (Bit 10), 
% and length 30 (field at 35) in R2 
% Gives a Prompt string in R3 
%+ The input is RAISE'd to upper case. 
% The Prompt will be typed if <Ctrl-R> is input 
Return RecopyStringToNULL S; 
% Since S will now possibly have a shorter 
4 string returned 
end; 


LJ 
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21.1. Introduction to the SYSLISP level of PSL 


SYSLISP [Benson 81] is a BCPL-like language, couched in LISP form, 
providing operations on machine words, machine bytes and LISP ITEMs (tagged 
objects, packed into one or more words). We actually think of SYSLISP as a 
lower level of PSL, dealing with. words, bytes, bit-fields, machine 
Operations, and compile-time storage allocation, enabling us to write 
essentially all of the kernel in PSL. 


The control structures and definition language are those of LISP, but the 
familiar Plus2, Times2, etc. are mapped to word operations WPlus2, WTimes2, 
etc. SYSLISP handles static allocation of SYSLISP variables and arrays and 
initial LISP symbols, permitting the easy definition of higher level 
Standard LISP functions and storage areas. SYSLISP provides convenient 
compile-time constants for handling strings, LISP symbols, etc. The 
SYSLISP compiler is based on the PORTABLE STANDARD LISP Compiler, with 
extensions to handle word level objects and efficient, open=coded, 
word-level operations. The SYSLISP mode of the compiler does efficient 
compile-time folding of constants and more comprehensive register 
allocation than in the distributed version of the PLC. Currently, SYSLISP 
handles bytes through the explicit packing and unpacking operations 
Get Byte (word-address, byte-number ) / 
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PutByte(word-address,byte-number,byte-value) without the notion of byte- 
pointer; it is planned to extend SYSLISP to a C-like language by adding the 
appropriate declarations and analysis of word/byte/structure operations. 


SYSLISP is a collection of functions and their corresponding data types 
which are used to implement low level primitives in PSL, such as storage 
allocation, garbage collection and input and output. The basic data object 
in SYSLISP is the "word", a unit of storage large enough to contain a LISP 
item. On the PDP-10, a SYSLISP word is just a 36-bit PDP~10 word. . On the 
VAX and most other byte addressed machines, a word is 4 bytes, or 32 bits. 
Conceptually, SYSLISP functions manipulate the actual bit patterns found in 
words, unlike normal LISP functions which manipulate higher-level objects, 
such as pairs, vectors, and floats or arbitrary-precision numbers. 
Arithmetic in SYSLISP is comparable to the corresponding operations in 
FORTRAN or PASCAL. In fact, SYSLISP is most closely modeled after BCPL, in 
that operations are essentially "typeless". 


21.2. The Relationship of SYSLISP to RLISP 


RLISP was extended with a CASE statement, SYSLISP declarations, smacros 
and macros to provide convenient infix syntax (+, *, / etc.) for calling 
the SYSLISP primitives. Even though SYSLISP is semantically somewhat 
different from LISP (RLISP), we have tried to keep the syntax as similar as 
possible so that SYSLISP code is "familiar" to RLISP users, and easy to 
use. RLISP functions can be easily converted and interfaced to functions 
at the SYSLISP level, gaining considerable efficiency by declaring and 
directly using words and bytes instead of tagged LISP objects. 


21.2.1. SYSLISP Declarations 

SYSLISP variables are either GLOBAL, memory locations (allocated by the 
compiler), or local stack locations. Locals are declared by SCALAR, as 
usual. Globals come in the following flavors: 
WCONST id = weonstexp {,id = wconstexp) ; 
Wconstexp is an expression involving constants and wconsts. 


WVAR wvardecl {, wvardecl} ; 


wvardecl ::= id | id = weonstexp 


WARRAY warraydecl {, warraydecl} ; 


warraydecl ::= id[wconstexp] | id[] = [ weonstexp {,weonstexp} ] 
| id{] = string 


wd 
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WSTRING warraydecl {, warraydecl} ; 

Bach of these declarations can also be prerixed witn the keywords: 

INTERNAL or EXTERNAL. 

If nothing appears, then a DEFAULT is used. 

(Notice there are no metasyntactic square brackets here, 


only curly brackets.) 


For example, the following GLOBAL-DATA is used in PSL: 


on SysLisp; 
exported WConst MaxSymbols = 8000, 
MaxConstants = 500, 
HeapSize = 100000; 
external WArray SymNam, SymVal, SymFnc, -SymPrp, ConstantVector; 
external WVar NextSymbol, NextConstant; 


exported WConst MaxRealRegs = 5, 
MaxArgs = 15; 


external WArray ArgumentBlock; 
off SysLisp; 


END; 


21.2.2. SYSLISP Mode Analysis 

In SYSLISP mode, the basic operators +, *, -, /, etC., are bound to word 
operators (WPlus2, WTimes2, WMinus, etc.), which compile OPEN as 
conventional machine operations on machine words. Thus most SYSLISP 
expressions, loops, etc. look exactly like their RLISP equivalents. 


21.2.3. Defining Special Functions for Mode Analysis 
To have the Mode analyzer (currently a REFORM function) replace LISP 
function names by SYSLISP ones, do: 


PUT('LispName, 'SYSNAME, 'SysLispName) ; 
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The Following have been done: 


DefList('((Plus WPlus2) 
(Plus2 WPlus2) 
(Minus WMinus) 
(Difference WDifference) 
(Times WTimes2) 
(Times2 WTimes2) 
(Quotient WQuotient) 
(Remainder WRemainder) 
(Mod WRemainder) 
(Land WAnd) 
(Lor Wor) 
(Lxor WXor) 
(Lnot WNot) 
(LShift WShift) 
(LSH WShift)), 'SysName); 


DefList('((Neq WNeq) 
(Equal WEq) 
(Eqn WEq) 
(Eq WEq) 
(Greaterp WGreaterp) 
(Lessp WLessp) 
(Geq WGeq) 
(Leq WLeq) 
(Getv WGetv) 
(Indx WGetv) 
(Putv WPutv) 
(SetIndx WPutv)), 'SysName); 


21.2.4. Modified FOR Loop 
The FOR loop is modified in SYSLISP mode to use the Wxxxx functions to do 
loop incrementation and testing. 


[222 Should pick up via SysReform ???] 


21.2.5. Char and IDLOC Macros 

In SYSLISP mode, '<id> refers to the tagged item, just as in LISP mode, 
IdLoc <id> refers to the id space offset of the <id>, and LispVar <id> 
refers to the GLOBAL value cell of a GLOBAL or FLUID variable. Note: 
LispVar can be used on the left hand side of an argument sentence. For 
example, to store a NIL in the value cell of id FOO, we do any one of the 
following. 


SYMVAL IDLOC FOO := 'NIL; 


LISPVAR FOO :2 MKITEM(ID, IDLOC NIL); 
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Char (U:id): integer macro 


The Char macro returns the ASCII code corresponding to its single 
character-id argument. CHAR also can handie alias's for certain special 
characters, remove QUOTE marks that may be needed to pass special 
characters through the parser, and can accept a prefixes to compute LOWER 
case, <Ctrl> characters, and <Meta> characters. For example: 


Little_a:= Char LOWER A; % In case we think RAISE will occur 
Little_a:= Char 'la; % la should not be raised 

Meta _X := Char META X; 

Weird <= Char META Lower X; 

Dinger := Char <Ctrl-G>; 

Dinger := Char BELL; 


The following Aliases are defined by PUTing the association under the 
indicator 'CharConst: 


DefList('((NULL 810) 
(BELL 817) 
(BACKSPACE 81410) 
(TAB 811) 
(LF 81/12) 
(EOL 8112) 
(FF 8/14) 
(CR 8:15) i 
(EOF 26) 
(ESC 27) 
(ESCAPE 27) 
(BLANK 32) 
(RUB 8#177) 
(RUBOUT 8#177) 
(DEL 8#177) . 
(DELETE 8#177)), 'CharConst); 


21.2.6. The Case Statement 

RLISP in SYSLISP mode provides a Numeric case statement, that is 
implemented quite efficiently; some effort is made to examine special cases 
(compact vs. non compact sets of cases, short vs. long sets of cases, 
etc.). 


[??? Note, CASE can also be used from LISP mode, provided tags are 
numeric. There is also an FEXPR, CASE ???] 


The syntax is: 
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Case-Sta 
Case-lis 
Case-exp 


tag-expr 


Tag 


% This i 

% in fil 
case 
0 to 
<< 


10: 
<< 


17: 


18: 
<< 
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tement ::= CASE expr OF case-list END 
t ¿5= Case-expr [; Case-list ] 
r iz Tag-expr : expr 
223 DEFAULT | OTHERWISE | 
tag | tag, tag +... tag | 
tag TO tag 
::= Integer | Wconst-Integer 
s a piece of code from the Token Scanner, 


e "PI:token-Scanner.red" 


ChTokenType of 
9: % digit 
TokSign += 1; 
goto InsideNumber >>; 
4 Start of ID 
if null LispVar !*Raise then 
goto InsidelD 
else 
<< RaiseLastChar(); 
goto InsideRaisedID >> >>; 
% Delimiter, but not beginning of diphthong 
LispVar TokType!* := '3; 
return MKID TokCh >>; 
% Start of comment 
goto InsideComment; 
% Diphthong start =- Lisp function uses P-list of starting char 
return ScanPossibleDipthong(TokChannel, MkID TokCh); 
% ID escape character 
if null LispVar !*Raise then 
goto GotEscape 
else goto GotEscapelnRaisedID >>; 
% string quote 
BackupBuf(); 
goto InsideString >>; 
p Package indicator - at start of token means use global package 
ResetBuf(); 
ChangedPackages := 1; 
Package 'Global; 
if null LispVar !*Raise then 
goto GotPackageMustGetID 
else goto GotPackageMustGetIDRaised >>; 
% Ignore - can't ever happen 
ScannerError("Internal error - consult a wizard"); 
% Minus sign 
TokSign := -1; 
goto GotSign >>; 
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19: % Plus sign 
<< TokSign := 1; 
goto GotSign >>; 
O: %.decimal point 
< ResetBuí(); 
ReadInBuf(); 
if ChTokenType >= 10 then 
<< UnReadLastChar(); 
return ScanPossibleDipthong(TokChannel, '!.) >> 
else 
<< TokSign := 1; 
TokFloatFractionLength := 1; 
goto InsideFloatFraction >> >>; 
default: . 
return ScannerError("Unknown token type") 
end; 


21.2.7. Memory Access and Address Operations 
The operators @ and & (corresponding to GetMem and Loc) may be used to do 
direct memory operations, similar to * and & in C. 


@ may also be used on the LHS of an assignment. Example: 


WARRAY FOO[10]; 
WVAR FEE=&FOO[0]; 


@(fee+2) := @(fee+4) + & foo(5); 


21.2.8. Bit-Field Operation 
The Field and PutField operations are used for accessing fields smaller 
than whole words: 


PUTFIELD(LOC, BITOFFSET, BITLENGTH, VALUE); 
and 
GETFIELD(LOC,BITOFFSET, BITLENGTH) ; 


Special cases such as bytes, halfwords, single bits are optimized if 
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possible. 


For example, the following definitions on the DEC-20 are used to define 
the fields of an item (in file p20c:data~machine.red): 


% Divide up the 36 bit DEC-20 word: 


WConst TagStartingBit = 0, 
TagBitLength = 18, 
StrictTagStartingBit = 9, 
StrictTagBitLength = 9, 
InfStartingBit = 18, 
InfBitLength = 18, 
GCStartingBit = 0, 
GCBitLength = 9; 


% Access to tag (type indicator) of Lisp item in ordinary code 


syslsp macro procedure Tag U; 
list('Field, cadr U, '(wconst TagStartingBit), '(wconst TagBitLength)); 


syslsp macro procedure PutTag U; 
list('PutField, cadr U, '(wconst TagStartingBit), 
'(wconst TagBitLength), caddr U); 


% Access to tag of Lisp item in garbage collector, 
% if GC bits may be in use 


syslsp macro procedure StrictTag U; 
list('Field, cadr U, '(wconst StrictTagStartingBit), 
t(wconst StrictTagBitLength)); 


syslsp macro procedure PutStrictTag U; 
list('PutField, | 
cadr U, '(weonst StrictTagStartingBit), 
t(wconst StrictTagBitLength), caddr U); 


% Access to info field of item (pointer or immediate operand) 


syslsp macro procedure Inf U; 
list('Field, cadr U, '(wconst InfStartingBit), '(weonst InfBitLength)); 


syslsp macro procedure Putinf U; 
list('PutField, cadr U, '(wconst InfStartingBit), 
t(wconst InfBitLength), caddr U); 
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21.3. Using SYSLISP 


Restriction: SYSLISP code is currently ONLY compiled, since it is 
converted into machine level operations, most of which are dangerous or 
tricky to use in an interpreted environment. 


Note: In SYSLISP mode, we currently execute some commands in the above 
PARSE/EVAL/PRINT mode, either to load files or select options, but most 
SYSLISP code is compiled to a file, rather than being immediately 
interpreted or compiled in-core. 


21.3.1. To Compile SYSLISP Code 

Use PSL:RLISP, which usually has the Compiler, with SYSLISP extensions, 
loaded. Alternatively, one may use <psl>syscmp.exe. This is a version of 
RLISP built upon <PSL>psl.exe with the SYSLISP compiler and data-machine 
macros loaded. 


% Turn on SYSLISP mode: 
ON SYSLISP; % This is causes the "mode-analysis" to be done 
% Converting some LISP names to SYSLISP names. 


% Use SYSLSP as the procedure type. 
Examples: 


% Small file to access BPS origin and end. 
% Starts in LISP mode 


Fluid '(NextBPO LastBP0); 


NextBP0:=NIL; 
LastBP0:=NIL; 


On SYSLISP,COMP; % Switch to SYSLISP mode 


syslsp procedure BPSize(); 

Begin scalar N1,L1; 
If Null LispVar NextBPO then LispVar NextBP0O:=GtBPS 0; 
If Null LispVar LastBPO then LispVar LastBP0:=GtWarray 0; 
Ni :=GtBPS(0); 
Lis= GtWarray(0); 
PrintF('" NextBPS=8#%0, used $d, LastBPS=8#%0, used fdén", 

N1, N1-LispVar(NextBP0), L1,LispVar(LastBP0)-L1); 

LispVar NextBP0:=N1; 
LispVar LastBP0:=L1; 

End; 


PSL Manual 17 June 1982 


page 21.10 


BPSize(); % Call the function 


21.4. SYSLISP Functions 


[??? What about overflow in Syslisp arithmetic? ??7] 


WPlus2 (U:word, V:word): word 
WDifference (U:sword, V:word): word 
WTimes2 (U:word, V:word): word 
WQuotient (U:word, V:word): word 
WRemainder (U:word, Viwora): word 
WShift (Usword, V:word): word 
WAnd (Uzword, V:word): word 

WOr (Usword, V:word): word 

WXor (U:word, Vsword): word 

WNot (Usword): word 

WEQ (Usword, V:word): boolean 


WNEQ (U:zword, V:word): boolean 


WGreaterP (U:word, V:word): boolean 
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WLessP (U:word, V:word): boolean 

WGEQ (U:word, V:word): boolean 

WLEQ (Usword, V:word): boolean 

WGetV (Usword, V:word): word 

WPutV (Usword, Vsword, Wsword): word 

Byte (Usword, V:word): word 


PutByte (U:word, V:word, W:word): word 


21.4.1. W-Arrays 
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open-compiled, expr 
open-compiled, expr 
open-compiled, expr 
open-compiled, macro 
open-compiled, macro 


open-compiled, expr 


open-compiled, expr 


CopyWArray (NEW:w-vector, OLD:w-vector, UPLIM:any): NEW:w-vector expr 


Copy UPLIM + 1 words. 


Like CopyWArray in heap. 


CopyWRDS (S:any): any 


Allocate new WRDS array in heap. 


21.5. Remaining SYSLISP Issues 


expr’ 


expr 


The system should be made less dependent on the assemblers, compilers and 
loaders of the particular machine it is implemented on. One way to do this 
is to bring up a very small kernel including a fast loader to load in the 


rest. 
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21.5.1. Stand Alone SYSLISP Programs 

In principle it works, but we need to clearly define a small set of 
support functions. Also, need to implement EXTERNAL properly, so that a 
normal LINKING loader can be used. In PSL, we currently produce a single 
kernel module, with resident LAP (or later FAP), and it serves as dynamic 
linking loader for SYSLISP (ala MAIN SAIL). 


21.5.2. Need for Two Stacks 

We must distinguisn between true LISP items and untagged SYSLISP items on 
the stack for the garbage collector to work properly. Two of the options 
for this are 


1. Put a mark on the stack indicating a region containing untagged items. 
2. Use a separate stack for untagged items. 


Either of these involves a change in the compiler, since it currently 
only allocates one frame for temporaries on the stack and does not 
distinguish where they get put. 


è 


The garbage collector should probably be recoded more modularly and at a 
higher level, short of redesigning the entire storage management scheme. 
This in itself would probably require the existence of a separate stack 
which is not traced through for return addresses and SYSLISP temporaries. 


21.5.3. New Mode System 
A better scheme for intermixing SYSLISP and LISP within a package is 
needed. Mode Reduce will probably take care of this. 


21.5.4. Extend CREF for SYSLISP 
The usual range of LISP tools should be available, such as profiling, a 
break package, tracing, etc. . 
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22.1. Overview of the Implementation 


In this Chapter we give a guide to the sources, although they are still 
rapidly changing. With these notes in mind, and an understanding of 
SYSLISP and tne compiler at the level of Chapters 19 and 21, it is hoped 
the user will be able to understand and change most of the system. Much of 
the current information is contained in comments in the source files, and 
cannot be reproduced here. 


[?2?? This Section needs a LOT of work ???] 


22.2. Files of Interest 


The complete sources are divided up into a fairly large number of files, 
spread over a number of sub-directories of <PSL>. This is so that files 
representing a common machine-independent kernel are in a single directory, 
and additional machine specific files in others. Furthermore, we have 
separated the compiler and LAP files from the rest of the files, since they 
are looked at first when doing a new implementation, but are not actually 
important to understanding the working of PSL. 


Some convenient logical device names are defined in <psl>logical- 
names.cmd. This file should have been TAKEn in your LOGIN.CMD. Current 
definitions are: 


; Officially recognized logical names for PSL subdirectories on UTAH-20 
define psl: <psl> ! Executable files and miscellaneous 
define ploc: <psl.local> ! Non-distributed miscellaneous 

define pi: <psl.interp> ! Interpreter sources 


AS 
mn 
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Compiler sources 

Utility program sources 
Non-distributed utility sources 
Documentation to TYPE 

Emode sources and build files 
Printer version of Documentation 
Help files 

LAP and B files 

Non-distributed LAP and B files 
Temporary home of Reduce built upon PSL 
Dec-20 specific interpreter sources 
Dec-20 specific compiler sources 
Dec-20 distribution files 

Vax specific interpreter sources 
Vax specific compiler sources 

Vax distribution files 

M68000 specific interpreter sources 
M68000 specific compiler sources 
Cray-1 interpreter sources 

Cray-1 compiler sources 

Cray-1 distribution files 

Search list for LOAD 


define pc: <psl.comp> 

define pu: <psl.util> 

define plocu: <psl.local.util> 
define pd: <psl.doc> ; 
define pe: <psl.emode> 

define plpt: <psl.ipt> 

define ph: <psl.help> 

define plap: <psl.lap> 

define ploclap: <psl.local.lap> 
define pred: <reduce.psl-reduce> 
define p20: <ps1.20-interp> 
define p20c: <ps1.20-comp> 
define p20d: <ps1.20-dist> 
define pv: <psl.vax-interp> 
define pve: <psl.vax-comp> 
define pvd: <psl.vax-dist> 
define p68: <ps1.68000-interp> 
define p68c: <ps1.68000-comp> 
define per: <psl.cray-interp> 
define perc: <psl.cray-comp> 
define perd: <psl.cray-dist> 
define pl: plap:,ploclap: 


ss A ee ee E E vue E E E ee ry 


Sources mostly live on PI:. DEC-20 build files and very machine specific 
files live on P20:. 


22.3. Building PSL on the DEC-20 
[2?? fix as FASL works ???] 


Building proceeds in number of steps. First the kernel files are 
compiled to MIDAS, using a LAP-to-MIDAS translator, which follows the 
normal LISP/SYSLISP compilation to LAP. This phase also includes the 
conversion of constants (atoms names, strings, etc) into structures in the 
heap, and initialization code into an INIT procedure. The resulting module 
is assembled, linked, and saved as BARE-~PSL.EXE. If executed, it reads in 
a batch of LAP files, previously compiled, representing those functions 
that should be in a minimal PSL, but in fact are not needed to implement 
LAP. 


[??? When FAP is implemented, these LAP files will become FAP files, 
and the kernel will get smaller ???] 


The BARE-PSL kernel build file is P20:PSL-KERNEL.CTL, and is reproduced 
here, slightly edited: 
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: This requires PL:PSL-NON-KERNEL.LAP and P20C:PSLDEF.MID 
copy BARE-PSL.SYM PSL.SYM 
PSL:MIDASCMP 


in 


POLLS RNE. RED: 


quit; 
MIDAS 
dpsl 
MIDAS 
spsl 
MIDAS 


psl 


load DPSL.REL, SPSL.REL, PSL.REL 
save BARE-PSL.EXE 


MIDASOUT "PSL"; 


IN 


"BINDING. RED"$ 
"FAST-BINDER.RED"$ 
"SYMBOL-VALUES.RED"$ 


"FUNCTION-PRIMITIVES.RED"S$ 


"OBLIST.RED"$ 
"CATCH-THROW.RED"$ 
"ALLOCATORS.RED"$ 
"COPIERS.RED"$ 
"CONS-MKVECT.RED"$ 
"GC. RED" $ 
"APPLY-LAP.RED"$ 
"EQUAL.RED"$ 
"EVAL-APPLY.RED"$ 
"PROPERTY-LIST.RED"$ 
"FLUID-GLOBAL.RED"$ 
"PUTD-GETD.RED"$ 
"KNOWN-TO-COMP-SL . RED" $ 
"OTHERS-SL.RED"$ 
"CARCDR.RED"$ 
"EASY-SL.RED"$ 
"EASY-NON-SL.RED"$ 
"COMP-SUPPORT.RED"$ 
"ERROR-HANDLERS.RED"$ 
"TYPE-CONVERSIONS.RED"$ 
"ARITH.RED"$ 
"TO-DATA.RED"$ 
"SYSTEM-IO.RED"$ 
"CHAR-I0.RED"$ 
"OPEN-CLOSE.RED"$ 
"RDS-WRS.RED"$ 
"OTHER-I0.RED"$ 
"READ. RED"$ 


Ba 


BA SA SA IA SA 32 DA BA 39 TA 39 39 BA VA VA SA 32 39 SA IJA A SA SA DA BA 59 39 BA VA 59 39 


! previously saved with LAPtoMIDAS 
File 


for kernel 


! assemble kernel data 


! assemble kernel init code 


! assemble kernel code 


! link into one module 
! save executable 


The kernel files mentioned in PSL-KERNEL.RED are: 


binding from the interpreter 

for binding in compiled code, in LAP 
SET, and support for Eval 

used by PutD, GetD and Eval 

Intern, Rem0b and GenSym , 
non-local GOTO mechanism - 
heap, symbol and code space alloc 
copying functions 

SL constructor functions 

the garbage collector 

low-level function linkage, in LAP 
equality predicates 

interpreter functions 

PUT and FLAG and friends 

variable declarations 

function defining functions 

SL functions performed online in code 
DIGIT, LITER and LENGTH 

CDDDDR, etc. 

highly portable SL function defns 
simple, ubiquitous SL extensions 
optimized CONS and LIST compilation 
low level error handlers 

convert from one type to another 
Lisp arithmetic functions 

Data structures used by IO 

system dependent IO functions 
bottom level IO primitives 

file primitives 

IO channel switching functions 
random SL 10 functions 

S-expression parser 
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IN "TOKEN-SCANNER.RED"S % 
IN "PRINTERS. RED'S % 
IN "WRITE-FLOAT. RED'S 
IN "PRINTF. RED'$ 4 
IN "IO-ERRORS.RED"S$ 4 
IN "IO-EXTENSIONS.RED"$ % 
IN "VECTORS, RED'S % 
IN "STRING-OPS,RED"3 % 
IN "EXPLODE-COMPRESS.RED"$ % 
IN "BACKTRACE.RED"$ Z 
IN "DEC-20-EXTRAS.RED"$ % 
IN "LAP.RED"S % 
IN "INTERESTING-SYMBOLS.RED"$ % 
IN "MAIN-START,RED"$ % 
MIDASEND; 

InitSymTab(); 

END; 
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table-driven token scanner 
Printing functions 

Floating point printer 
formatted print routines 

I/O error handlers 

Random non-SL IO functions 
GetV, PutV, UpbV 

Indx, SetIndx, Sub, SetSub, Concat 
Access to characters of atoms 
Stack backtrace 

Dec-20 specific routines 
Compiled code loader 

to access important WCONSTs 
first routine called 


The current non-kernel files are defined in PSL-NON-KERNEL.RED: 


LapOut "PL: PSL-NON-KERNEL.LAP"; 
in "EVAL-WHEN,RED"$ 

in "CONT-ERROR.RED"$ 

in "MINI-TRACE.RED"S$ 

in "TOP-LOOP.RED"$ 

in "PROG-AND-FRIENDS.RED"$ 
in "ERROR-ERRORSET,RED"$ 
in "TYPE-ERRORS.RED"$ 

in "SETS,.RED"$ 

in "DSKIN.RED"$ 

in "LISP-MACROS.RED"$ 

in "LOOP-MACROS.RED"$ 

in "CHAR.RED"$ | 

in "LOAD,RED"$ 

in "PSL-MAIN.RED"$ 

LapEnd; 


SR IA 32 39 SA 32 VA GA TA 32 GA FA ya 


The model on the VAX is similar. 


The file 
LAP-to-Assembly phase. 


A symbol table file, PSL.SYM is 


in independent recompilation of 


locations of WVARS, WARRAYS, and WSTRINGs, etc. 


control evaluation time (load first) 
macro for ContinuableError 

Simple function tracing 

generalized top loop function 

Prog, Go and Return 

most basic error handling 

type mismatch error calls 

Set manipulation functions 
Read/Eval/Print from files 

If, SetF 


.While, Repeat, ForEach 


Character constant macro 
Standard module LAP loader 
% SaveSystem and Version stuff 


GLOBAL-DATA.RED is automatically loaded by the compiler in the 
It defines most important external symbols. 


produced, and is meant to be used to aid 
modules. It records assigned ID numbers, 
It is not currently used. 


UY 
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The file P20C:DATA-MACHINE.RED defines important macros and constants, 
allocating fields within a DEC-20 word (the TAGs, ete). It is used only 
witn compiled code, and is so associated with the P20C: (20 compiler 
Specific code); other files on this directory include the code-generator 
tables and compiler customization files. More information on the compiler 
and its support can be found in Chapter 19. 


22.4, Building the LAP to Assembly Translator 


[??? Write after new table-driven LAP and LAP-to-ASM is stable ?77] 


22.5. The Garbage Collectors and Allocators 


22.5.1. Compacting Garbage Collector on DEC-20 

DEC-20 PSL uses essentially the same compacting garbage collector 
developed for the previous MTLISP systems: a single heap with all objects 
tagged in the heap in such a way that a linear sean from the low end 
permits objects to be identified; they are either tagged as normal objects, 
and are thus in a PAIR, or are tagged with a "pseudo-tag", indicating a 
header item for some sort of BYTE, WORD or ITEM array. Tracing of objects 
is done using a small stack, and relocation via a segment table and extra 
bits in the item. The extra bits in the item can be replaced by a 
bit-table, and this may become the default method. 


During compaction, objects are "tamped" to the low end of the heap, 
permitting "genetic" ordering for algebraic operations, and rapid 
Stack-like allocation. 


Since the MTLISP systems included a number of variable sized data-types 
(e.g. vectors and strings), we had to reduce the working set, and ease the 
addition of new data-types, by using a single heap with explicitly tagged 
objects, and compacting garbage collector. In some versions, a bit-table 
was used both for marking and for compaction. To preserve locality, 
structures are "tamped" to one end of the heap, maintaining relative 
(creation time or "Genetic" [Terashima 78]) ordering. The order 
preservation was rather useful for an inexpensive canonical ordering 
required in the REDUCE algebra system (simply compare heap positions, which 
are "naturally" related to object creation). The single heap, with 
explicit tags made the addition of new data-types rather easy. The virtual 
memory was implemented as a low level "memory" extension, invisible to the 
allocator and garbage collector. 


This garbage collector has been rewritten a number of times; it is fairly 
easy to extend, but does waste lot of space in each DEC-20 word. Among 
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possible alternative allocators/GC is a bit-table version, which is 
semantically equivalent to that described above but has the Dmoy field 
replaced by a procedure to count ones in a segment of the bit-table. At 
some point, the separate heap model (tried on 2-80 and PDP-~11 MTLISP's) may 
be implemented, but the separate page-per-type method (BIBOP:="big bag of 
pages") might also be tried; this permits user definition of new types. 


Allocation proceeds as from a stack, permitting rapid allocation, and 
preserving creation time ordering. The current implementation uses a 
recursive mark phase with a small stack (G stack) of about 500 entries. 


Relocation is accomplished with aid the of the SEGMENT table (overlays G 
stack), and a small field (Dmov) in each item (header) that gives 
additional motion of this item relative to the relocation of its segment. 


22.5.2. Two-Space Stop and Copy Collector on VAX 
Another alternative is a copying, 2-space GC, which is fast and good for 
large address space (e.g. extended addressing DEC~20 or VAX). 


22.6. The HEAPs 


The HEAP is used to store variable sized objects. Since one of the 
possible implementations is to have a separate heap for each of the data 
types PAIR, STR, CODE, and VECT (or for the groupings PAIR, CODE+STR, 
VECT), the heap is accessed in type specific fashion only. The current 
implementation of the allocator and garbage collector maps these 
type-specific operations onto a single array of item sized blocks, the 
first of which is a normal tagged item (CAR of a PAIR), or a pseudo-item 
(header of CODE, -STR or VECT). The following blocks are either tagged 
items or packed bytes. The header item contains a "length" in items, or 
bytes, as appropriate. Using item sized blocks results in a slight wastage 
at the end of strings and code-vectors. 


Reclamation: 


h:=INF(x) For garbage collection, compaction and relocation. The heap is 
viewed as a set of ITEM sized blocks 

PUTINF(x,h) 

PUTTYPE(x,t) 

MARK (h) 

UNMARK(h) Modify the garbage collector mark 

MARKED(h) Test the mark (in a bit-table, ITEM header, or ITEM itself). 


Other Garbage collector primitives include: 


5 


a 


J 
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GCPUSH(x) Push an ITEM onto GCSTACK for later trace 

Xx :=GCPOP() 
Retrieve ITEM for tracing 

xi:=GCTOP() 

Examine top of GCSTACK 


Tne Garbage collector uses a GCSTACK for saving pointers still to be 
traced, The compaction and relocation takes place by "tamping", without 
structure reorganization, so that any structure is relocated by the same or 
more than a neighboring structure, lower in the heap. This "monotonicity" 
means that the heap can be divided into "segments", and the relocation of 
any structure computed as the relocation of its segment, plus an additional 
movement within the segment. The segment table is an additional structure, 
while the "offset" is computed from the bits in the bit-table, or from a 
small field (if available) in the ITEM. This garbage collector is similar 
to that described in [Terashima 78]. 


RELOC (h) : =SEGKNT(SEG(h))+DMOV(h) 
SEGKNT(SEG(h)) is the segment relocation of the segment in which 
h is, and DMOV is the incremental move within this segment. 


i:=SEG(h) Computes the segment number 


i:=DSEG(h) 
The "offset" in the segment 


Note that DMOV may actually be a small field in an ITEM header, if there 
is space, or can be computed from the bits in a segment of the BIT-table, 
or may map to some other construct. The segment table may actually overlay 
the GCSTACK space, since these are active in different passes of the 
garbage collection. Tne garbage collector used in the MTLISP system is an 
extension of that attributed to S. Brown in [Harrison 73, Harrison 74]. 
See also [Terashima 78]. 


1*GC (Initially: NIL) flag 
!*GC controls the printing of garbage collector messages. If NIL 
no indication of garbage collection occurs. If non-NIL various 
system dependent messages may be displayed. 

GCKNT!* (Initially: 0) global 
Records the number of times that Reclaim has been called to this 


point. GCKNT!* may be reset to another value to record counts 
incrementally, as desired. 
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Reclaim (): integer expr 


User call on GC; does a mark-trace and compaction of HEAP, 
Returns size of current Heap top. If !*GC is T, prints some 
statistics. Increments GCKNT!*. Reclaim(); is the user level 
call to the garbage collector. 


iZReclaim (): expr 
!'%Reclaim(); is the system level call to the garbage collector. 
Active data in the heap is made contiguous and all tagged 
pointers into the heap from active local stack frames, the 
binding stack and the symbol table are relocated. 

22.7. Allocation Functions 

GtHEAP (NWRDS:word): word expr 
Return address in HEAP of a block of NWRDS item sized pieces. 
Generates HeapOverflow Message if can't satisfy. GtHeap NIL; 
returns the number of words (Lisp items) left in the heap. 

A GtHeap 0; returns a pointer to the top of the active heap. 
GtHeap N; returns a pointer to N words (items). 

GtStr (UPLIM:word): word expr 
Address of string, 0..UPLIM bytes. (Allocate space for a string 
UPLIM characters.) 

GtConstStr (N:string): expr 
(Allocate un-collected string for print name. Same as GtStr, but 
uses BPS, not heap.) 

GtWrds (UPLIM:word): word expr 
Address of WRD, 0..UPLIM WORDS. (Allocate space for UPLIM 
untraced words.) 

GtVect (UPLIM:word): word expr 


Address of vector, UPLIM items. (Allocate space for a vector 
UPLIM items.) i 


C 


C 


J 
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GtFixN (): s-integer expr 


Allocate space for a fixnum. 


GtFltN (): s-integer expr 


Allocate space for a float. 


GtID (): id expr 


Allocate a new id. 


GtBps (N:3-integer): s-integer expr 


Allocate N words for binary code. 


GtWArray (N:s-integer): s-integer expr 


Allocate N words for WVar/WArray/WString. 
DelBps (): expr 


DelWArray (): expr 


GtBps NIL; returns the number of words left in BPS. GtWArray NIL returns 
the same quantity. 


GtBps 0; returns a pointer to the bottom of BPS, that is, the current 
value of NextBPS. GtWArray 0; returns a pointer to the top of BPS, the 
current value of LastBPS. This is sometimes convenient for use with DelBps 
and DelWArray. 


GtBps N; returns a pointer to N words in BPS, moving NextBPS up by that 
amount. GtWArray returns a pointer to (the bottom of) N words at the top 
of BPS, pushing LastBPS down by that amount. Remember that the arguments 
are number of WORDS to allocate, that is, 1/4 the number of bytes on the 
VAX or 68000. 


DelBps(Lo, Hi) returns a block to BPS, if it is contiguous with the 
current free space. In other words, if Hi is equal to NextBPS, then 
NextBPS is set to Lo. Otherwise, NIL is returned and no space is added to 
BPS. DelHeap(Lo, Hi) is similar in action to DelBps. 
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DelWArray(Lo, Hi) returns a block to the top of BPS, if it is contiguous 
with the current free space. In other words, if Lo is equal to lLastBPS, 
then LastBPS is set to Hi. Otherwise, NIL is returned and no space is 
added to BPS. 


The storage management routines above are intended for either very long 
term or very short term use. BPS is not examined by the garbage collector 
at all. The routines below should be used with great care, as they deal 
with the heap which must be Kept in a consistent state for the garbage 
collector. All blocks of memory allocated in the heap must have header 
words describing the size and type of data contained, and all pointers into 
the heap must have type tags consistent with the data they refer to. 


C 


J 


PSL Manual 17 June 1982 Parser Tools 
section 23.0 page 23.1 
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23.1. Introduction 


In many applications, it is convenient to define a special 
"problem-oriented" language, tailored to provide a natural input format. 
Examples include the RLISP ALGOL-like surface language for algebraic work, 
graphics languages, boolean query languages for data-base, etc. Another 
important case is the requirement to accept existing programs in some 
language, either to translate them to another language, to compile to 
machine language, to be able to adapt existing code into the PSL 
environment (e.g. mathematical libraries, etc.), or because we wish to use 
PSL based tools to analyze a program written in another language. One 
approach is to hand-code a program in PSL (called a "parser") that 
translates the input language to the desired form; this is tedious and 
error prone, and it is more convenient to use a "parser-writing-tool". 


In this Chapter we describe in detail two important parser writing tools 
available to the PSL programer: an extensible table-driven parser that is 
used for the RLISP parser (described in Chapter 3), and the MINI parser 
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generator. The table-driven parser is most useful for languages that are 
simple extensions of RLISF, or in fact for rapidly adding new syntactic 
constructs to RLISP. The MINI system is used for the development of more 
complete user languages. 


iv 


3.2. The Table Driven Parser 


The parser is a top-down recursive descent parser, which uses a table of 
Precedences to control the parse; if numeric precedence is not adequate, 
LISP functions may be inserted into the table to provide more control. The 
parser described here was developed by Nordstrom [Nordstrom 73], and is 
very Similar to parser described by Pratt [Pratt 73], and apparently used 
for the CGOL language, another LISP surface language. 


The parser reads tokens from an input stream using a function Scan. Scan 
calls the ChannelReadToken function described in Chapter 13, and performs 
some additional checks, described below. Each token is defined to be one 
of the following: 


non-operator O 
right operator 0-> 
binary operator <-0-> 


All combinations of .. .0-> OQ... and O <-O->. . . are supposed to be 
legal, while the combinations +. +. .0=> <=-0=->. . e} è è .<=0=> <-0->. . . 
and 0 0... are normally illegal (error ARG MISSING and error OP MISSING, 
respectively). 


With each operator (which must be an id) is associated a construction 
function, a right precedence, and for binary operators, a left precedence. 


The Unary Prefix operators have this information stored under the 
indicator 'RLISPPREFIX and Binary operators have it stored under 
'RLISPINFIX. (Actually, the indicator used at any time during parsing is 
the VALUE of GRAMPREFIX or GRAMINFIX, which may be changed by the user). 


23.2.1. Flow Diagram for the Parser 

In this diagram RP stands for Right Precedence, LP for Left Precedence 
and CF for Construction Function. OP is a global variable which holds the 
current token. 
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procedure PARSE(RP 


E 
RDRIGHT(RP,SCAN())3 % SCAN reads next token 


RDRIGHT(RP,Y) 
| 
MM / 
| 
| | yes 
| Y is Right OP | oc cn > Y:=APPLY(Y.CF,RDRIGHT(Y.RP)); 
| | 
| e 
\l/ no R 
| A 
ERROR yes| | no g 
ARG <---- | Y is Binary OP |----> OP:= a 
MISSING | | SCAN(); . 
¡sosa css ds cotas * 
RDLEFT: \|/ i ^ 
| A 
ERROR nol | ^ 
OP Lema | OP is Binary | j 
MISSING | | > 
| A 
\l7 yes = 
| A 
RETURN yes| Ino ^ 
(Y) Lam | RP > OP.1p | -=--> Y:=APPLY(OP.cf,Y, 
A PARSE(OP.1p,SCAN()); 
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This diagram reflects the major behavior, though some trivial additions 
are ineluded in the RLISP case to handle cases such as OP-> <-OP, '!3, ete. 
[See PU:RLISP-PARSER.RED for full details. ] 


The technique involved may also be described by the following figure: 


. » - O-> Y <-0, e . 
rp 1p 


Y is a token or an already parsed expression between two operators (as 
indicated). If 0->'s RP is greater than <-0's LP, then 0-> is the winner 
and Y goes to 0->'s construction function (and vice versa). The result 
from the construction function is a "new Y" in another parse situation. 


By associating precedences and construction functions with the operators, 
we are now able to parse arithmetic expressions (except for function calls) 
and a large number of syntactical constructions such as IF - THEN - ELSE 
- 3 etc. The following discussion of how to expand the parser to cover a 
language such as RLISP (or ALGOL) may also be seen as general tools for 
handling the parser and defining construction functions and precedences. 


23.2.2. Associating the Infix Operator with a Function 

The Sean, after calling RAtomHook, checks ids and special ids (those with 
TOKTYPE! * = 3) to see if they should be renamed from external form to 
internal form (e.g. '!+ to Plus2). This is done by checking for a NEWNAM 
or NEWNAM!-OP property on the id. For special ids, the NEWNAM!-OP property 
is first checked. The value of the property is a replacement token, i.e. 


PUT(*! +, 'NEWNAM!-OP, 'PLUS2) 
has been done. 


Scan also handles the ' mark, calling RlispRead to get the S-expression. 
RlispRead is a version of Read, using a special SCANTABLE, 
RLISPREADSCANTABLE!*. 


The function Scan also sets SEMIC!* to '!; or '!$ if CURSYM!* is detected 
to be '!*SEMICOL!* (the internal name for '!; and "!$). This controls the 
RLISP echo/no-echo capability. Finally, if the renamed token is 'COMMEN 
then characters are ReadCh'd until a '!3 or "i$. . 
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23.2.3. Precedences 

To set up precedences, it is often nelpful to set up a precedence matrix 
of tne operators involved. If any operator nas one "precedence" with 
respect to one particular operator and another "precedence" with respect to 
some other, it is sometimes not possible to run the parser with just 
numbered precedences for the operators without introducing ambiguities. If 
this is the case, replace the number RP by the operator RP and test with 
something like: 


IF RP *GREATER* OP... 


#GREATER* may check in the precedence matrix. An example in which such a 
scheme might be used is the case for which ALGOL uses ":" both as a label 
marker and as an index separator (although in this case there is no need 
for the change above). It is also a good policy to have even numbers for 
right precedences and odd numbers for left precedences (or vice versa). 


23.2.4. Special Cases of 0 <-0 and 0 0 


If ...00... is a legal case (i.e. F A may translate to (F A)), 
ERROR OP MISSING is replaced by: 


Y :=REPCOM(Y,RDRIGHT(99,0P)); GO TO RDLEFT; 


The value 99 is chosen in order to have the first object (F) behave as a 
right operator with maximum precedence. If .. .0 <-0. . . is legal for 
some combinations of operators, replace ERROR ARG MISSING by something 
equivalent to the illegal RLISP statement: 


IF ISOPOP(OP,RP,Y) 
THEN <<OP:3=Y; 
Y:=(something else, i.e. NIL); 
GOTO RDLEFT>> 
ELSE ERROR ARG MISSING; 


ISOPOP is supposed to return T if the present situation is legal. 
23.2.5. Parenthesized Expressions 
(a) is to be translated to a. 


E.g. 
BEGIN a END translates to (PROG a). 
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Define "(" and BEGIN as right operators with low precedences (2 and -2 
respectively). Also define ")" and END as binary operators with matching 
left precedences (1 and -3 respectively). The construction functions for 
*(" and BEGIN are then something like: [See pu:RLISP-PARSER.RED for exact 
details on ParseBEGIN] 


BEGIN (X) sPROG2(OP:=SCAN( ) ¡MAKEPROG(X)); 
n(n (X);PROG2(IF OP=") THEN OP:=SCAN() 


ELSE ERROR, x}; 


Note that the construction functions in these cases have to read the next 
token; that is the effect of ")" closing the last "(" and not all earlier 
"("tg. This is also an example of binary operators declared only for the 
purpose of having a left precedence. 


23.2.6. Binary Operators in General 
As almost all binary operators have a construction function like 


LIST(OP,X,Y); 


it is assumed to be of that kind if no other is given. If OP is a binary 
operator, then "a OP b OP e" is interpreted as "(a OP b) OP ce" only if OP's 
LP is less than OP's RP. 


Example: 
A + B + C translates to (A + B) +C 
because +'RP = 20 and +'LP = 19 
A ^ B ^ C translates to A ~*~ (B ^ C) 


because ^'RP = 20 and ^'LP = 21 


If you want some operators to translate to n-ary expressions, you have to 
define a proper construction function for that operator. 


Example: 


PLUS (X,Y); IF CAR(X) = 'PLUS THEN NCONC(X,LIST(Y)) 
ELSE LIST('PLUS,X,Y); 


By defining "," and ";" as ordinary binary operators, the parser 


od 


—J 


tJ 
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automatically takes care of constructions like . . .€,2@,@,¢,e. + and 
a » +. Stmsstmsstmsstm;. .. It is then up to some other operators to 
remove the "," or the "3" from the parsed result. 


23.2.7. Assigning Precedences to Key Words 
If you want some operators to have control immediately, insert 


IF RP = NIL THEN RETURN Y ELSE 


as the very first test in RDRIGHT and set the right precedence of those to 
NIL. This is sometimes useful for key-word expressions. If entering a 
construction function of such an operator, X is the token immediately after 
the operator. E.g.: We want to parse PROCEDURE EQ(X,Y); . +. . Define 
PROCEDURE as a right operator with NIL as precedence. The construction 
function for PROCEDURE can always call the parser and set the rest of the 
expression. Note that if PROCEDURE was not defined as above, the parser 
would misunderstand the expression in the case of EQ as declared as a 
binary operator. 


23.2.8. Error Handling 

For the present, if an error occurs a message is printed but no attempt 
is made to correct or handle the error. Mostly the parser, goes wild for a 
while (until a left precedence less than current right precedence is found) 
and then goes on as usual. 


23.2.9. The Parser Program for the RLISP Language 
SCAN(); 


The purpose of this function is to read the next token from the input 
stream. It uses the general purpose table driven token scanner described 
in Chapter 13, with a specially set up ReadTable, RLISPSCANTABLE!*. As 
RLISP has multiple identifiers for the same operators, Scan uses the 
following translation table: 
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= EQUAL >= GEQ 
+ PLUS > GREATERP 
- DIFFERENCE <= LEQ 
/ QUOTIENT < LESSP 
- CONS # TIMES 
s= SETQ ## EXPT 


In these cases, Scan returns the right nand side of the table values. 
Also, two special cases are taken care of in Scan: 


ae ' is the QUOTE mark. If a parenthesized expression follows '! 
then the syntax within the parenthesis is that of LISP, using a 
special scan table, RLISPREADSCANTABLE!*. The only major 
difference from ordinary LISP is that ! is required for all 
special characters. 


b. ! in RLISP means actually two things: 
i. the following symbol is not treated as a special symbol 
(but belongs to the print name of the atom in process); 


ii. the atom created cannot be an operator. 
Example: !( in the text behaves as the atom "(". 


To signal to the parser that this is the case, the flag variable ESCAPEFL 
must be set to T if this situation occurs. 


23.2.10. Defining Operators 
To define operators use: 


DEFINEROP(op,p{,stm}); 
For right or prefix operators. 


DEFINEBOP(op,lp,rp{,stm}); 
For binary operators. 


These use the VALUE of DEFPREFIX and DEFINFIX to store the precedences 
and construction functions. The default is set for RLISP, to be 
'RLISPPREFIX. and 'RLISPINFIX. The same identifier can be defined both as. 
the right and binary operator. The context defines which one applies. 
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Stm is the construction function. If stm is omitted, the common defaults 
E y 


LISTCOP;x) 
prefix case, x is parsed exoression following, 
x=RDRIGHT(p,SCAN()). 


LIST(OP,x,y) 
binary case, x is previously parsed expression, y is expression 
following, y=RDRIGHT(rp,SCAN()). 


If stm is an id, it is assumed to be a procedure of one or two arguments, 
for ugn or "x,y". If it is an expression, it is embedded as 
(LAMBDA(X) stm) or (LAMBDA(X Y) stm), and should refer to X and Y, as 
needed. 


Also remember that the free variable OP holds the last token (normally 
the binary operator which stopped the parser). If "p!" or "rp" is NIL, 
RDRIGHT is not called by default, so that only SCAN() (the next token) is 
passed. 


For example, 


DEFINEBOP( 'DIFFERENCE, 17,18); 
+ Most common case, left associative, stm=LIST(OP,x,y); 


DEFINEBOP( 'CONS, 23,21); 
% Right Associative, default stm=LIST(OP,x,y) 


DEFINEBOP('AND,11,12,ParseAND); 
% Left Associative, special function 
PROCEDURE ParseAND(X,Y); 
NARY('AND,X,Y); 


DEFINEBOP( 'SETQ,7,6,ParseSETQ) ; 
% Right Associative, Special Function 
PROCEDURE ParseSETQ(LHS,RHS); 
LIST(IF ATOM LHS THEN 'SETQ ELSE 'SETF, LHS, RHS); 


DEFINEROP('MINUS,26); % default C-fn, just (list OP arg) 
DEFINEROP('PLUS,26,ParsePLUS1); % 
DEFINEROP('GO,NIL,ParseGO ); 

$ Special Function, DO NOT use default PARSE ahead 


PROCEDURE ParseGO X; X is now JUST next-token 
IF X EQ 'TO THEN LIST('GO, PARSEO(6,T)) 
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% Explicit Parse ahead 
ELSE <<OP 32 SCAN(); % get Next Token 
LIST('G0,X)>>; 


DEFINEROP(*GOTO,NIL,ParseGOTO ); 
% Suppress Parse Ahead, just pass NextToken 
PROCEDURE ParseGOTO X; 
<<OP 3= SCAN(); 
LIST('GO,X)>>; 


23.3. The MINI Translator Writing System 


Note that MINI is now autoloading. 


23.3.1. A Brief Guide to MINI 

The following is a brief introduction to MINI, the reader is referred 
to [Marti 79] for a more detailed discussion of the META/RLISP operators, 
which are very similar to those of MINI. 


The MINI system reads in a definition of a translator, using a BNF-like 
form. This is processed by MINI into a set of LISP functions, one for each 
production, which make calls on each other, and a set of support routines 
that recognize a variety of simple constructs. MINI uses a stack to 
perform parsing, and the user can access sub-trees already on the stack, 
replacing them by other trees built from these sub-trees. The primitive 
functions that recognize ids, integers, etc. each place their recognized 
token on this stack. 


For example, 
FOO: ID '!- ID +(PLUS2 #2 #1) ; 


defines a rule FOO, which recognizes two identifiers separated by a minus 
sign (each ID pushes the recognized identifier onto the stack). The last 
expression replaces the top 2 elements on the stack (#2 pops the first ID 
pushed onto the stack, while #1 pops the other) with a LISP statement. 


Id (): boolean expr 


See if current token is an identifier and not a keyword. If it 
is, then push onto the stack and fetch the next token. 
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Anyla (): boolean expr 


See if current token is an id whether or not it is a key word. 


AnyTok (): boolean expr 


Always succeeds by pushing the current token onto the stack. 


Num (): boolean expr 


Tests to see if the current token is a number, if so it pushes 
the number onto the stack and fetches the next token. 

Str (): boolean expr 
Same as Num, except for strings. 

Specification of a parser using MINI consists of defining the syntax with 
BNF-1ixe rules and semantics with LISP expressions. The following is a 
brief list of tne operators: 

Used to designate a terminal symbol (i.e. 'WHILE, 'DO, '!=). 


Identifier 
Specifies a nonterminal. 


( ) Used for grouping (i.e. (FOO BAR) requires rule FOO to parse 
followed immediately by BAR). 

<> Optional parse, if it fails then continue (i.e. <FOO> tries to 

: parse FOO). 

/ Optional rules (i.e. FOO / BAR allows either FOO or BAR to parse, 
with FOO tested first). 

STMT* Parse any number of STMT. 

STMT[ ANY TOKEN ]# 


Parse any number of STMT separated by ANYTOKEN, create a list and 
push onto the stack (i.e. ID[,]* parses a number of identifiers 
separated by commas, like in an argument list). 


din Refer to the nth stack location (n must be an integer). 
in Pop the nth stack location (n must be an integer). 


+(STMT) Push the unevaluated (STMT) onto the stack. 
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-(SEXPR) Evaluate the SEXPR and ignore the result. 
=(SEXPR) Evaluate the SEXPR and test if result non-NIL. 
++ (SEXPR) Evaluate the SEXPR and push the result on the stack. 


@ANYTOKEN Specifies a statement terminator; used in the error recovery 
mechanism to search for the occurrence of errors. 


@@ ANYTOKEN 
Grammar terminator; also stops scan, but if encountered in 
error-recovery, terminates grammar. 


23.3.2. Pattern Matching Rules 

In addition to the BNF-like rules that define procedures with O arguments 
and which scan tokens by calls on NEXT!-TOK() and operate on the stack, 
MINI also includes a simple TREE pattern matcher and syntax to define 
PatternProcedures that accept and return a single argument, trying a series | 
of patterns until one succeeds. 


E.g. template => replacement 


PATTERN = (PLUS2 &1 0) -> &1, 
(PLUS2 &1 &1) -> (LIST 'TIMES2 2 &1), 
&1 -> &1; 


defines a pattern with 3 rules. &n is used to indicate a matched sub-tree 
in both the template and replacement. A repeated &n, as in the second 
rule, requires Equal sub-trees. 


23.3.3. A Small Example 

% A simple demo of MINI, to produce a LIST-NOTATION reader. 

% INVOKE 'LSPLOOP reads S-expressions, separated by ; 

mini 'lsploop; % Invoke MINI, give name of ROOT 


% Comments can appear anywhere, 
% prefix by $ to end-of-line 


1sploop:1sp* @@# ; 4% @@# is GRAMMAR terminator 
% like '# but stops TOKEN SCAN 
lsp: sexp €; % €; is RULE terminator, like '; 
«(print #1) % but stops SCAN, to print 
«(next!-tok) ; % so call NEXT!-TOK() explicitly 


sexp: id / num / str / '( dotexp ') ; 
dotexp: sexp* < '. sexp +.(attach #2 #1) > 3 
fin 
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symbolic procedure attach(x,y); 

<<for caen z in reverse x do y322 +» y; y?>; 


23.3.4. Loading Mini 
MINI is loaded from PH: using LOAD MINT;. 


23.3.5. Running Mini 

A MINI grammar is run by calling Invoke rootname;. This installs 
appropriate Key Words (stored on the property list of rootname), and start 
the grammar by calling the Rootname as first procedure. 


23.3.6. MINI Error messages and Error Recovery 

If MINI detects a non-fatal error, a message be printed, and the current 
token and stack is shown. MINI then calls NEXT!-TOK() repeatedly until 
either a statement terminator (@ANYTOKEN) or grammar terminator (@ANYTOKEN) 
is seen. If a grammar terminator, the grammar is exited; otherwise parsing 
resumes from the ROOT. 


[??? Interaction with BREAK loop rather poor at the moment 777] 


23.3.7. MINI Self-Definition 


? The following is the definition of the MINI meta system in terms of 

2 itself. Some support procedures are needed, and exist in a separate 
% file. l 

4 To define a grammar, call the procedure MINI with the argument being 
% the root rule name. Then when the grammar is defined it may be 

% called by using INVOKE root rule name. 

$ The following is the MINI Meta self definition. 

MINI 'RUL; 


% Define the diphthongs to be used in the grammar. 
DIP: !#!H#, l-1>, I+l., 1018 ; 


% The root rule is called RUL. 
RUL: ('DIP ': ANYTOK[,]* .(DIPBLD #1) '; / 
(ID .(SETQ !#LABLIST!# NIL) 
( ts ALT +(DE #2 NIL #1) 0; / 
'= PRUL[,]* €; + (RULE!-DEFINE '(PUT (QUOTE ##2) (QUOTE RB) 
(QUOTE #1))) 
+(DE ##1 (A) 
(REMATCH A (GET (QUOTE #1) (QUOTE RB)) NIL))) 
-(RULE!-DEFINE #1) .(NEXT!-TOK) ))* @@FIN ; 


% An alternative is a sequence of statements separated by /'s; 
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ALT: SEQ < '/ ALT +(0R #2 #1) >; 


% A sequence is a list of items that must be matched. 
SEQ: REP < SEQ +(AND #2 (FAIL!-NOT #1)) >; 


% A repetition may be 0 or more single items (#) or 0 or more items 
% separated by any token (ID[,]%* parses a list of ID's separated 

> by ,*'3. 

REP: ONE 


<I (ID +(#1) / 
1? ANYKEY +(EQTOK!-NEXT (QUOTE #1)) / 
ANYKEY +(EQTOK!-NEXT (QUOTE #1))) '] +(AND #2 #1) '* BLD!-EXPR / 
1# BLD!-EXPR>; 


% Create an sexpression to build a repetition. 
BLD!-EXPR: +(PROG (X) (SETQ X (STK!-LENGTH) ) 
$1 (COND (#1 (GO $1))) 
(BUILD!-REPEAT X) 
(RETURN T)); 


ANYKEY: ANYTOK .(ADDKEY ##1) 3; % Add a new KEY 


% One defines a single item. 
ONE: '' ANYKEY +(EQTOK!-NEXT (QUOTE #1)) / 
'@ ANYKEY .(ADDRTERM ##1) +(EQTOK (QUOTE #1)) / 
198 ANYKEY .(ADDGTERM ##1) +(EQTOK (QUOTE #1)) / 
'+ UNLBLD + (PUSH #1) / : 
t. EVLBLD +(PROGN #1 T) / 
t= EVLBLD / 
' ALT '> +(PROGN #1 T) / 
'( ALT ') / 
"+. EVLBLD +(PUSH #1) / 
ID +(#1) 3 


% This rule defines an un evaled list. It builds a list with everything 
% quoted. 
UNLBLD: '( UNLBLD ('. UNLBLD ') +(CONS #2 #1) / 
UNLBLD* ') +(LIST . (#2 . #1)) / 
') +(LIST +. #1)) / 
LBLD 7 
ID +(QUOTE #1) ; 


%  EVLBLD builds a list of evaled items. 
EVLBLD: '( EVLBLD ('. EVLBLD ') +(CONS #2 #1) / 
EVLBLD* ') +(#2 . #1) / 
t) ) / . . . 
LBLD / 
ID ; 


LBLD: '# NUM +( EXTRACT #1) / 
'## NUM +(REF #1) / 
'$ NUM +(GENLAB #1) / 


it 
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'& NUM +(CADR (ASSOC #1 (CAR VARLIST))) / 
NUM / 
STi / 
tt ("£ UNLBLD# *) +(LIST . $1) / 
ANYTOK +(QUOTE #1)); 


% Defines the pattern matching rules (PATTERN -> BODY). 
PRUL: .(SETQ INDEXLIST!# NIL) 
PAT '-> (EVLBLD)* 
+(LAMBDA (VARLIST T1 T2 T3) (AND . #1)) 
. (SETQ PNAM (GENSYM)) 
«(RULE!-DEFINE (LIST 'PUTD (LIST 'QUOTE PNAM) 
'(QUOTE EXPR) (LIST 'QUOTE #1))) 
++ (CONS #1 PNAM); 


Defines a pattern. 
We now allow the . operator to be the next to last in a (). 
AT: '£ ('< PSIMP[/]* '> NUM 
+. (PROGN (SETQ INDEXLIST!* (CONS ##1 INDEXLIST!*)) 
(LIST '!& #2 #1) ) / 


'U B ga 


NUM 
++ (COND ((MEMQ ##1 INDEXLIST!*) 
(LIST '!& '!& #1)) 
(T (PROGN (SETQ INDEXLIST!* (CONS ##1 INDEXLIST!*)) 

(LIST '!& #1)))) ) 

ID 

'!( PAT® <'. PAT +.( APPEND #2 #1)> '!) 

'' ANYTOK 

STR 

NUM ; 


NS Nao 


% Defines the primitives in a pattern. 
PSIMP: ID / NUM / '( PSIMP* ') / *! ANYTOK; 
? The grammar terminator. 
FIN 


23.3.8. The Construction of MINI 

MINI is actually described in terms of a support package for any 
MINI-generated parser and a self-description of MINI. The useful files (on 
PU: and PL:) are as follows: 


MINI.MIN The self definition of MINI in MINI. 
MINI.SL A Standard LISP version of MINI.MIN, translated by MINI itself. 
MINI.RED The support RLISP for MINI. 
MINI-PATCH.RED and MINI.FIX 
Some additions being tested. 
MINI.LAP The precompiled LAP file. Use LOAD MINI. 
MINI-LAP-BUILD.CTL 
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A batch file that builds PL:MINT.LAP from the above files. 
MINI--SELF-BUILD.CTL 

A baten file that builds tne MINI.SL file by loading and 

translating MINIT.MIN. 


23.3.9. History of MINI Development 

The MINI Translator Writing System was developed in two steps. The first 
was the enhancement of the META/RLISP [Marti 79] system with the definition 
of pattern matching primitives to aid in describing and performing 
tree-to-tree transformations. META/RLISP is very proficient at translating 
an input programming language into LISP or LISP-like trees, but did not 
have a good method for manipulating the trees nor for direct generation of 
target machine code. PMETA (as it was initially called) [Kessler 79] 
solved these problems and created a very good environment for the 
development of compilers. In fact, the PMETA enhancements have been fully 
integrated into META/RLISP. 


The second step was the elimination of META/RLISP and the development of 
a smaller, faster system (MINI). Since META/RLISP was designed to provide 
maximum flexibility and full generality, the parsers that is creates are 
large and slow. One of its most significant problems is that it uses its 
own single character driven LISP functions for token scanning and 
recognition. Elimination of this overhead has produced a faster 
translator. MINI uses the hand coded scanner in the underlying RLISP. The 
other main aspect of MINI was the elimination of various META/RLISP 
features to decrease the size of the system (also decreasing the 
flexibility, but MINI has been successful for the various purposes in COG). 
MINI is now small enough to run on small LISP systems (as long as a token 
scanner is provided). The META/RLISP features that MINI has changed or 
eliminated include the following: 


a. The ability to backup the parser state upon failure is supported 
in META/RLISP. However, by modifying a grammar definition, the 
need for backup can be mostly avoided and was therefore 
eliminated from MINI. 


b. META/RLISP has extensive mechanisms to allow arbitrary length 
diphthongs. MINI only supports two character diphthongs, 
declared prior to their use. 


ec. The target machine language and error specification operators 
are not supported because they can be implemented with support 
routines. 

d. RLISP subsyntax for specification of semantic operations is not 
supported -(only LISP is provided). 


Although MINI lacks many of the features of META/RLISP, it still has been 
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quite sufficient for a variety of languages. 


23.4. BNF Description of RLISP Using MINI 


The following formal scheme for the translation of RLISP syntax to LISP 
syntax is presented to eliminate misinterpretation of the definitions. We 
nave used the above MINI syntactic form since it is close enough to BNF and 
nas also been checked mechanically. 


Recall that the transformation scheme produces an S-expression 
corresponding to the input RLISP expression. A rule has a name by which it 
is known and is defined by wnat follows the meta symbol :. Each rule of 
the set consists of one or more "alternatives" separated by the meta symbol 
/, being the different ways in which the rule is matched by source text. 
Each rule ends with a ;. Each alternative is composed of a "recognizer" 
and a "generator". The "generator" is a MINI + expression which builds an 
S-expression from constants and elements loaded on the stack. The result 
is then loaded on the stack. The #n and ##n refer to elements loaded by 
MINI primitives or other rules. The "generator" is thus a template into 


which previously generated items are substituted. Recall that terminals in 


both recognizer and generator are quoted with a ' mark. 


This RLISP/SYSLISP syntax is based on a series of META and MINI 
definitions, started by R. Loos in 1970, continued by M. Griss, R. Kessler 
and A. Wang. 


[22? Need to confirm for latest RLISP ??7] 


mini 'rlisp; 
dip: l: 9 I< 3 1>1> , {sis 9 181% 9 !<l= 9 1>!= 9 pa 9 tt # 3 


termin: '; / '$ ; % $ used to not echo result 
rtermin: @; / @$ ; 


rlisp: ( cmds rtermin .(next!-tok) )* ; % Note explicit Scan 
emds: procdef / rexpr ; 
Ma Procedure definition: 


procdef: emodeproc (ftype procs/ procs) / 
ftype procs / procs ; 


ftype: 'fexpr .(setq FTYPE!* 'fexpr) / % function type 
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‘macro .(setq FIYPE!* 'macro) / 
'smacro .(setq FTYPE!* 'smacro) / 


'nmacro .(setq FIYPE!* 'nmacro) / 
(expr / =T) .(setq FIYPE!® 'expr) ; 


emodeproc: 'syslsp .(setq EMODE? 'syslsp)/ 
('lisp/'symbolic/=T) .(setq EMODE!* 'symbolic) ; 


procs: 'procedure id proctail 
+(putd (quote #2) (quote FTYPE!* ) #1) ; 
proctail: '( id[,]* *) termin rexpr +(quote (lambda #2 #1)) / 
termin rexpr +(quote (lambda nil #1)) / 
id termin rexpr +(quote (lambda (#2) #1)) ; 
don Rexpr definition: 
rexpr: disjunction ; 
disjunction: conjunction (disjunctail / =T) ; 


disjunctail: ('or conjunction ('or conjunction) *) 
+.(cons tor (cons #3 (cons #2 #1))) ; 


conjunctions: negation (conjunctail / =T) ; 


conjunctail: ('and negation ('and negation) *) 
+.(cons (quote and) (cons #3 (cons #2 #1))) ; 


negation: 'not negation +(null #1) / 

- "null negation +(null #1) / 

relation ; 

relation: term reltail ; 
reltail: relop term +(#2 #2 #1) / =T; 
term: ('- factor +(minus #1) / factor) termtail ; 
termtail: (plusop factor +(#2 #2 #1) termtail) / =T ; 
factor: powerexpr factortail ; 
factortail: (timop powerexpr +(#2 #2 #1) factortail) / =T ; 


powerexpr: dotexpr powtail ; 


powtail: ('** dotexpr +(expt #2 #1) powtail) / 


$" 
+3 


dotexpr: primary dottail ; 
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ttail: ('. primary +(cons #2 #1) dottail) / =T ; 


orimary: ifstate groupstate / beginstate / 
whilesta / repeatstate / forstmts / 
definestate / onoffstate / lambdastate / 
('( rexpr ?) ) / 
(7? (lists / id / num) +(quote #1)) / 
id primtail / num ; 


/ 
t 


2 


primtail:(':= rexpr +(setq #2 #1)) / 

'; labstmts ) / 

'( actualst / (primary +(#2 #1)) / =T ; 
lists: '( (elements)* ') ; 
elements: lists / id / num ; 


Pr If statement: 


ifstate: 'if rexpr 'then rexpr elserexpr 
+(cond (#3 #2) (T #1)) ; 


elserexpr: ‘else rexpr / =T +nil ; 
Pan While statement: 


whilestate: ‘while rexpr 'do rexpr 
+(while #2 #1) ; 


Brno Repeat statement: 


repeatstate: 'repeat rexpr 'until rexpr 
+(repeat #2 #1) ; : 


Z---- For statement: 
forstmts: 'for fortail ; 
fortail: ('each foreachstate) / forstate ; 


foreachstate: id inoron rexpr actchoice rexpr 
+(foreach #5 #4 #3 #2 #1) ; 


inoron: ('in +in / 'on +on) ; 


actchoice: ('do +do / ‘collect +collect / ‘cone +conc) 


we 


forstate: id ':= rexpr loops ; 


loops: (': rexpr types rexpr 
+(for #5 (#4 1 #3) #2 #1) ) / 
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('step rexpr ‘until rexpr types rexpr 
+(for #5 (#5 #4 #3) #2 #1) ) 3 


types: ('do +do / 'sum +sum / ‘product +product) ; 

dr Function call parameter list: 

actualst: ') +(#1) / rexpr[,]* ') +.(cons #2 #1) ; 
Dr Compound group statement: 

groupstate: '<< rexprlist '>> +.(cons (quote progn) #1) ; 
Jo a e e Compound begin-end statement: 

beginstate: ‘begin blockbody 'end ; 


blockbody: decllist blockstates 
+. (cons (quote prog) (cons #2 #1)) ; 


decllist: (decls[;]* +.(flatten #1)) / (=T +nil) ; 
decls: (‘integer / 'scalar) id[,]* ; 
blockstates: labstmts[;]* ; 
labstmts: ('return rexpr +(return #1)) / 
((tgoto / 'go 'to) id +(go #1)) / 
("if rexpr 'then labstmts blkelse 
+(cond (#3 #2) (T #1))) / 
rexpr ; 
blkelse: ‘else labstmts / =T +nil ; 
rexprlist: rexpr [;]* ; 
lambdastate: ‘lambda lamtail ; 
lamtail: '( id[,]* ') termin rexpr +(lambda #2 #1) / 
termin rexpr +(lambda nil #1) / 


id termin rexpr +(lambda (#2) #1) ; 


Yo o Define statement: (id and value are put onto table 
% named DEFNTAB: 


definestate: 'define delist +.(cons (quote progn) #1) ; 


delist: (id '= rexpr +(put (quote #2) (quote defntab) 
(quote #1)))[,J* ; 


der On or off statement: 


PEN 


a 
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onoffstate: 


tim 


o 


lists: 


p 


f AA 
¡US 
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(ton +T / "off enil) fla 
‘defn +(set 'itdefn #1) ; 


+times / '/ +quotient) ; 


plusop: ('+ +plus2 / '- «+difference) 


3 


relop: ('< +lessp / ‘<= +lep / '= sequal / 


FIN 


'>= +gep / '> +greaterp) 


, 
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ENTRACE= sa % n we aw coer a Flag 16.17 
#TRACEALL. a è s s è o > o lag 16.11, 16.15 
1#TRCOUNT e ea s e o at ťa o a Flag 16.18 
I ŽTRUNKNOWN es e e e ¿è [lag 16.17 
t #UNSAFEBINDER. a... . . flag 19,23 
I *USEREGFLUID . . +... « . « flag 19.23 
ISUSERMODE. . . . s © © o . o flag 10.3 
\CreatePackage. . » s . .. . expr 6.9 
\CURRENTPACKAGE?*® . . . . . . global 6.8 
\LocalIntern. +. ae se e e EXpr 6.10 
\LocalInternP . . . . . . » . €Xpr 6.10 
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ContError . . . e s. e è e > Macro 15.3 
ContinuableError. . . . . . . expr 15.3 
COPYs. = soe a a o a a expr 7.3 
COPYD a Ed e a Se te ee e a expr ` 10.3 
CopyScanTable . . . . ə e » » expr 13.11 
COPYSTELNES e e e èe e > >» > EXpr 8.2 
CopyStringToFroM. . » +. . + . expr 8.2 
CopyVectors: w..6 40% e è e 6 EXDr 8.4 
CopyVectorToFroM. ..... +» expr 8.3 
CODY WATYAV se od eee. è e > > SOR 21.11 
CopyWRDS. .... . > > e « » expr 21.11 
CopyWRDSToFrom. ...... + expr . 21.11 
COS a: <p ah eo ee ee tas ete BS CERDE 18.26 
COSDy Sace Bie a ee ls A ERE -18.27 
COU se ta: e a e a ERD 18.27 
COEDS. a. Ai ane ee uk arc er es Gh GDF 18.27 
CPrivite.s: a e e “a ane sk. oe SRO 18.24 
CRLF; s e del soe eo o e a w v global 20.2 
CSC ae A a n a a es, Ce RDP - 18.27 


CSOD arete E a XDE 18.28 
CURRENTSCANTABLE!*, . . . . . global 13.7, 13.10, 13.11, 13.18 


Der A dia a ar 10.4 
DOCKS e aa MACRO 5.3 

DefConst. e e.s èe è > è è we > macro 18.21 
DefLambda . . . . . +... « » macro 18.13 
DefList . . IT o o o o o AE 6.4 

DefMacro. e.e s e o e o o e macro 18.11 
Defstruüuct s s è o e @ s a e o fexpr 18.15 
DefstructP. pce Boe, ae! eS es EXPE 18.15 


DefstructType ....... . expr 18.15 
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DegreesToRadians. ..... + expr 
Dal es e e o e SDr 
DelAsSes 4. s s % a a de e XD 
DELAS e ov ee E A 2 
AA w w sera BAe, Sd a CBOE 
DebacOlPre e So ao ww Se Ae Se ERDF 
DeLBoSs- Ara e ee. ia RP 
DELETE; ee o aa. Ae ee a Ses SS edit 
Delete. mea a o Se o a EXpr 
DSL OGLE a so po e lee LS a e 
DEL Qe. a Je dorat as Wi ee Bt SRE 
DOL OEP a: da ae os HS er wt es CER DE 
DelWArray mx. e o e expr 
DeSetQ. 1... e e o o o o > Macro 
DES E AAN ee ITO 
DFPRINT!* a e e e e è Bo e global 
Difference. e s.. s o e e e e CXpr 
Digit!-Char . 4 « « 2%. e « « expr 
Digit s.a Sosa. Soke ter Bink oar as we EXD 
DigitP. a as è es ee OO 
Divides. a e a e A a BP 
Dmi oa a e A EPO 
DMSToRadians. . a . «© « « e . €Xpr 18.26 
DAs ee ek os hs, ee oe. Tar MOO 10.4 
Dolo ao ci GS a dk ee MEO 9.15 
Do~Loop!*® . . . a s 6 © © ws . macro. 9.15 
Do-Loop . a e s e o e è è o . macro 9.15 
DO AT E MOO 9.14 
DoCmdS. 2 e s è s as è e e EE 20.2 
Dt E RA e ae NACL 10.5 
DSkIñ s ow s ca ee 4 we expr 13.12 
DumpLiSPp. a s è s e > è > e BPE 14.2 


è 


— O 
O 


se NM. 
MO ww 00 we 


2 UO = OV — e ANN NNN MN -A-—-3-1 
mM +. . « . 
ÑO] 


EditF ae te. We dee e e Xp 17.11 
EditENS ocs la a e ever expr 17.11 
EditP de e laa ep ee a TE ONDE 17.11 
EditV a ca do a a o e PO XDL 17.11 


y 

4 

A a a. dy eana a te a 0 4, 

Equal s e o s ae soe ens w apre Y 

Se a 1 

ERRORFORM!* . 5 . . e . « o global 15.3, 15.4 
ERRORHANDLERS!* , . . . . . +. global 15.8 
ErrorPrintF . . . e e e è > DE 13.15 
Error5et. e & s e wow è expr 15.2 
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ERROUTI*. e o > e e global 13.3, 13.15 
ENPRPD A a Ei SES. a OAOT 13.1: 
Lo cde e a a . expr 11.1 
EvaliIninvironment ..... » expr 19.10 
EVED ua Li o a RD 13.12 
BVLLS s s as rs expr 11.3 
EvProgN . 2 2 s e s o e e a ODA 11.3 
EXC s e w a a a a e a DE 20.3 
BX LG se. il anne oo e Ac Sane ee eer 9.7 
EXD hp) cay Ue Sor WO) tar a ae: Gl we SER PE 18.29 
Expand. Ss s s è o o e e we «KDE 11.4 
Explode2. s s e s o er a o EXpr 13.19 
Explöde «s s» e e e s è Bote o © SKOF 13.19 


EXPRES Seca do a Se ODE 10.6 
EXDES “a Sw RDA 5.3 

Extended-Get. . . s e e . > +. expr 18.23 
Extended-PUt. . ». e s e e > « eXpr 18.23 
EXTRACT e So w s a vedit 17.12 


Esus scal e a aa eet a ect a We CREE 17.14 

E a a A Aa oe edit 17.2, 17.12 
FaslEnd s e s èo è o >» >» Xpr 19.2 

Fas ite: ec ky s- woe a a e e a Expr 19.3 
FaslOut > e e e se w e a æ e BAD 19.2 
FCõdeP. o © sos wa Sarat a DA 10.5 
FEXDERS oc e Wk St a ABRE 10.6 

FileP . Y s sss a o o EXpDr 13.4, 20.5 
FindPrefiX. . . . . . +. . . . expr 18.22 
Pind out lists: . . . a e Sled e DL 18.22 

First s e-e cee Ve e ch eh aS Set ce MÁS 7.4 

FIX e e a E O ae es SRD 5.2 
ELX Paves ce a a a a EX DE 4.7 
A ASI ee vat ee oe SER 6.5 
FLAG a: e aoe. Boe a Se el ew e e expr 6.4 
Pag e aa ra ae expr 6.5 
FLambdaLinkP. . . e . è . e > expr 1 
FlatSize2 4 re ce è èe > > EXPE 13.20 
FlatSizZze. Ww a is e o e o o > expr 13.19 
¡NI E 5.2 
FloatPe ooe e a Se a a ve 28 RDF 4.7 

PAL! e a o DR 10.7, 19.5 
FlūidP. > e Gre. w è eri os a BEDE 10.8 


FORE: do a w e a e, MACRO 9.12 
POP a a Se ew. a a MACKS 9.8 
FOrEach . . e e» > èe è e o » Macro 9.12 
Fourth. s s è s a s è >- œ e macro ¡ENE 


AA A A A edit 17.13 
POCUD ta. whe. So me: ch. AC, Se “SRP 16.13 
FUnBoundP + . . s eo. « è e e @Xpr 10.5 
Function. . s. e e s e è e a FORDE 11.4 


GCKNT!* oases o e o ee global 22.7 
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GenSym. « «expr 0.3 
Gea. macro 5.5 
cet. : expr 6.3 
GecTDir . expr 20.6 
GetD. a Se expr 10.3 
GetFCodePointer . +. expr 10.6 
GetFork . . . a expr 20.4 
GetNewJfín . . e » expr 20.5 
GetOldJfn . . « e expr 20,5 
GetRescan . . expr 20.5 
GetUName. . expr 20.6 
GetV. A E expr 8.2 
Global. . “ . expr 10.7, 19.5 
Global? us. $ 18 e +. expr 10.8 
GMergeSort. e +. expr 7.11 
E Bee ds eh <8 . . fexpr 9.5 
Graph-to-Tree . «e . expr 18.24 
GraphicP. . . ¿4 expr 8.7 
GreaterP. . e expr 5.5 
GSort . ; e . expr T.11 
GSortP. « .. + +. expr 7.11 
GtBps . . : . . expr 22.9 
GtConstStr. . e . expr 22.8 
GtFixN. .. . « expr 22.9 
GtF1tN. .. «e +. expr 22.9 
GtHEAP. . . . . expr 22.8 
GEID; 2. -2.. 6.4 <. . expr 22.9 
GtJfn .... . . expr 20.6 
GEST Geos. aS . expr 22.8 
GtVect. ... e +. expr 22.8 
GtWArray. . . e . expr 22.9 
GtWrdS. . . . . . expr 22.8 
HAppend... e +. expr 18.23 
HCONS da te <4 . . macro 18.23 
HOODY 0 + » macro 18.23 
HELP. sco du e . edit 17.3, 17.14 
Help. Ly e e . fexpr 14,5 
HelpDir . . . + « expr 20.3 
Helpln!*, .. e + global 14.5 
HelpOut!* . , .« « global 14.6 
HighHalfWord. . > expr 20.8 
Hist. .. % + . nexpr 14,4 
ALSO > e sa e +. nexpr 18.23 
HReverse. +. . e » expr 18.23 
La a: eels . e edit 17.14 
Id2Int. ... e +. expr 4.10 
Id2String . . e 2 expr 4.10 
Ide e s e ana e « expr 23.10 
IdP aa a + » expr 4.7 
IdSortFn. . . + > expr 7.10 


Function Index 26 July 1982 PSL Manual 
page 25.8 section 25.0 


EER E AR ERA AAA OO 17.14 
A A O Macro 9.2 
If System... . . e. s » . cmacro 20.1 
IGetV A XDF 8 
Implode . . s a > s e e a DE 1 
Imports: De ta c oia o a ADE 1 
IN Rac oaee e a a es a BLobal 1 13.4, 13.18 
SS a A a MRS 1 

LAOS ese a e MEO 5 

TAN e e Re do a ae TOE 8 

InFileèes a >» e A e a FORDE 2 

Ea ay ay o a ee a SKE 14,4 

INSERT si e a OLE 17.14 


Inspect . s.. e o e e» e ao Xpr 18.24 
Tnth=Char s s s e s & o ws a BEDE 8.9 
Int2Id. . s e e o s è e o ORR DP 4,10 
Int2Str o se we we ee So es es ee a VOR DE 20.8 
Int25yS .. ss ess e SS o COPE 4.10 
INEerNe ee a a tale es ae a Er 4.9 
InterñP s-s e a a A e expr 6.3 
InterpBackTrace ...... . expr 155 
InterSectioñ. . . e e s e e e EXpr 7.8 


InterSectionQ . . «+ +s. a> è > >» DE 7 
DRUG ao aie ae a O eee BERD 2 8 
ISiZeSe s s a o Ros a SA RDA 8. 
TSt Ze Ve. oo eo: ae Sie a e Se aeRO 8 


JBits © e èo > òo >ù © èo # ọọ ò 6o expr 20.9 


JCONV or we r w RE a a es we CDr 20.7 
TITO eee gle Meee a a Be ee OED 20.7 
JSYVS a aa ot GS SEK DF 20.7 
A ee > > > o o o OK PL 20.7 
JSYS3 E E 20.7 


PSV A eH NPL 20.7 
RELIP ORK 6 s Ae s e e ooa “SORE 20.4 


LANAS ses ss oos o o RDA 5.7 
GAP c foc wl os a a Bo a ak RD 19.9 
Lapin ens e a fal ew aa Ye? a Ses es CER DE 13.12 
LASTACTUALREG . ....... global 19.23 
LastCar «ca s sew rs EXD 7.5 
LastPair. > e c ce-a e w a s a epr 7.5 
LB TS ee, e». èe e è è a CXDr 10.9 
LOS e w 2 eS day ads a ar edit 17.14 
LCL- w a a a a a Ob 17.15 
LCONG. o. w e a as Dr ed 
Lengths cs se As a do SS Se ee Me ORD 7.6 
Leg “sa; ee ce. Za hs Seth nan Se eh HO de ze “SP AMG 5.5 
LESS Po e iow: ek. ae a a Dr 5.5 
LOGE o eca de e A e da MOTO 9.1 
Leto io de a e Macro 9.1 
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Lo ee. y ‘ . edit 17.15 
LineLength . 2xpr 13.16 
LispEqual ‘ . expr 46 
LISPSCANTABLE! * « global 13.7, 13.10, 13.18 
List2Set. . expr 7.9 
List25etQ . tee >. expr 7.9 
List2String . . e Bxpe 4.10 
List2Vector . . o» expr 4.11 
AA . . fexpr 7.6 
A woa E a . expr 13.19 
ENDE @ & iw 4 . expr St 
LOS og es os BS a «e +. edit 17.15 
¡1 s s e sa + . macro 19.3 
LoadTime. . . . . expr 19.4 
EGETO e we ds . > expr 18.29 
Log2. «+ fe . . expr 18.29 
LOS e de ses a eee e . expr 18.29 
GOR jas a amean, te ot e +. expr 5.7 
LowerCaseP. . . . +. expr 8.7 
LowHalfWord . . e . expr 20.8 
GP x. ma ao + . edit 17.16 
LPosn . 4 < «< :Bxpr 13.16 
EPO: Yoo Se a .« » edit 17.16 
LShift. Es e > eXpr Bal 
LXO: Ho “as ee e e . expr 5.7 
O aer ei e . edit 17.16 
MacroExpand . . + . macro 18.13 
MacroP. .... e > expr 10.6 
Mains s s s ea ¿+= expr 14,2 
Make!-Bytes . . «e +. expr 8.4 
Make !-Halfwords o expr 8.4 
Make!-String. e EXPr 8.2, 8.11 
Make!-Vector. . e . expr 8.3 
Make!-Words . . . . expr 8.4 
MakeFCode . . . e +. expr 10.6 
MakeFLambdaLink E expr 10.5 
MAKEFN. . . . +. e . edit 17.17 
MakeFUnBound. . +. . expr 10.5 
MakeUnBound . . e © expr 6.8 
MaD cas. de os A > 92) 8 9.13 
MapC. s... +. +. expr 9.13 
MapCan. .... + » expr 9.13 
MapCars . .. à e +. expr 9.13 
MapCon. ... . e +. expr 9.13 
Maplist .... + +. expr 9.14 
MapObl. e... e o expr 6.4 
MARK. see’ « . edit 17.17 
Mal. fen. ae ee + +. expr 5.6 
Mak ga. an oa tes A + +. macro 5.6 
MAXLEVEL. . . è e » global 17.13 
MAXNARGS. +. +. + e + global 19.24 
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MBD Car a a WUE 17.18 
Member. . e s s s s e > o s o @XDr 
MEMOS: de e ow gee a e A EO 
PAZ. ew. a o OI, e e A a BRE 
MIN e a a Se, ee e w Maro 
MENÚS” s e e a A e So, e AKE 
MINUS Pe s ae e a E e TON 
MKQUOCE: n s s e s s s s a @XDr 
MESEPINGs « waa e o > e e > EXPr 
MKVECE io e E aca A ds PERE 
MMe a es e ee Since, Ta. a KDE 
MOVES o e a ee Se ae eo Se, Hh oe. SEAS 17.18 


. 
A ON 


WM 09 O -—2 U1 U1 UV NAN 


Nos aow AS A Ae a BLE 17.19 
NameFromJin: . . us e e e > e XpDr 20.6 
NCONC e a e o e o è o >o o >» o CXpDr T.T 
NCONS -s e ee cel o. a Er 7.3 
NGG. at a e a e sae a Lan LBXDE 4.6 
Neq Lia a o o o o o MACKS 4.6 
NewId . . es e e o o>» o o o MORDE 4.9 
NewTrBuff . .. . + «© © « > « expr 16, 
NEX ¿ua ve. e a E o ds TALE 1 
NEXSDPP ss 4 da aa a ra Apr 10. 
MOD: oa) Glee a e e macro 9.7 
NIL- Ss eee eG ae a Ge la e a BL ODSL 12.4 
NOLTSIEE aa s e s> > o e global 18.3 
NOD. ea a EA DES 4.8 
NString!-Capitalize .... . expr 8.12 
NString!-DownCase . . . ». > . expr 8.11 
NString!-UpCase . . . . . . e expr 8.11 
NTH è o e s w s o E dit 17.19 
NER- e e a a e ERP 149 
Muller a ee SDE 4.8 
NOM: 2 ow 5 ee, e a RDP `~ 23.11 
NumberP « « o... .. >» e è è « > @xpr 4.8 
NumberSortFn. . . e ə e ə è> +. €Xpr T.10 
NX- a boda tv e a a e edit 17.20 


OTE do ca a aa Macro © 12.2 

DES al a ee ra aria CUL 17.3, 17.20 
Ds. des a aa a e as de Maro 12.2 

OEP o i Bs ds oe Se ata DE 5.6 

Opens a a Sew, Sa, Se EXPE 13.3 
OpenFork. . . . » s è . « > « @Xpr 20.4 
OpenNewJfn. . . . © e e © © o EXpr 20.5 
OpenOldJfn. . . . « e « e è . expr 20.5 
OPTIONS!* ©.. o e e o o e e o global 19.3 ` 

Ore a 6 a, o a e sa LOXxpr 4.9 

ORF O AAA e ar BOL 17.20 

ORR a: e ee a as e Ow BALL 17321 
OUT us ee ee o a a o o o global 13.2, 13.4 
QUE a a E ao a, Hee we a Dr 13.12 


Pi ao cae ORY o A 
PUEVEDS dba ala 
PLISE e ar a 
¡AS 
PAS. e da 
PNG a vna, tbr cue es. S 
POD: a s e ar at ee 
POS w ot wm te ES 
Pee Go as we a a8 
PDL noure ae eo Ae 
PPFPRINTER!*, , . 
PrettyPrint ... 
Pra soe ana s a 
Prinz- e a a as 
Prin2L; œ eS a 
Praineles «. e e 
Print e e s a w a 
PACs e-e ooa a 
PrintScanTable. . 
PrintX. Sa! le œ 
Progi s.s.s’ 
PROBE els e e ae 
PROG et: o s ba 
ProgN A 
PROMPTSTRING!*, . 
Prop. s- e e “eee os 
PROPERTYPRINTER! * 
PSELE ui “oe. a 
POCEO AA 
PUSH ls Se va 
PUC- y Se. 6. 68) 85 os 
PutByte e .. à 
PUED, a da 
PUTDHOOK!*. ... 
PutDipthong . . + 
PutReadMacro. . . 
PutRescan .... 
PUG Ve o ee SS 


Quit. . e e e e . 
Quote . . s.. eà 
Quotient. . . à 


R e o e e e e e e 
RadiansToDegrees. 
RadiansToDMS. .. 
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Random; s wnr a a RBD 18.29 
RATOM enwa e a A a a ODE 73.9 
HGS eter er o oh, ee et See e xe ER DE 13,4 
CE AS A e 13.18 
ReadCH. a tac a RD 13.5 
ReadChar. asos e s o o o > APA 13.5 
ROCÍD + s a w ho. e. sas... COREL 5.4 
Reelaim . . s. s e s s > èe è COREE 22.8 
RecopyStringToNULL. . . . . . expr 20.8 
ReDo. è s a a a so Macro 14,4 
RelJfn. ess ae o o expr 20.5 
Remainder 6.46 s.. s oe e s ODP 5.4 
RemD. e e w e o so e o e e @Xpr 10.4 
RemFlagl. «esos “se e è è e. OXpr 6.5 
RemPlag ==“... es . è e e expr 6.5 
-RemOb o de ss es e o pr 6.3 
RemProp e . es e e s e o oè » EXpr 6.4 
RemPropL. + al è a XDR 6.4 
REPACK: Ve a a a dLE 17.23 
Repeat. e s s s s s e > > e macro 9.7 
ReSBE A a a RDE 16.12 
Reset ra see a DE 14,2, 20.4 
RESTA a a Se MACRO: o TeS 
RestoreEnvironment. . . . . . expr 10.10 
Restr s a: cg oo a erate ae ee 2 EXPE 16.10 
Return. a. s s e s ee e o o “OXDP 9.6 
Reverse e... sss o o èo o CXpDr 7.9 
ReversIP., ass è o è ADE 7.10 
AE RM eds OTE 17.23 
REISD -s a erne e SR e e aoa e DE 14.5 
RLISPSCANTABLE!*. . . . . . +» global 13.7, 13.10 
RD. AR a e e a BALE 17.24 
Round +. a e es > o expr 18.26 
¡A o a 6) A T.4 
RplacD. e.. > ee Ww o a e EXpr 7.4 
RplaChar. oe. a OXDE 8.9 
RplacW. . ae he è èe è e > aa ORD 7.4 
RPrinte -s Se; 38) «ea? He ee ORE 13.16 
RUN- att a eee es e A EOP 20.3 
RunFork 2 @ es èe s è e è OXF 20.4 
ere AR eae A OLE 17.24 
DÁSSOS. a s a o 2412... we BEPC 7.12 
SAVES ae <a Ma Gl a de a SALE 17.24 
SaveSystem. . . e. s . e e o expr 14.1 
ScaledCosine. . . . . e o e » expr 18.26 
ScaledCotangent . . . e . + . expr 18.27 
ScaledSine. . . . « « « « » « @xpr 18.26 
ScaledTangent . . . s. e e . . expr 18.27 
OO A ar e ORDO 18.27 
SECU se ds es ae Ce EXD 18.27 


SECOND. ssec e s o e Cdit 17.24 
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Second macro LaS 
Set . ; expr 6.6 
SetF. . macro 6.7 
Set Indx A expr 8.5 
A s as a Wo tp A ee ` expr 6.5 
e E a a Mart wes o a a fexpr 6.6 
SetSub. . è A expr da 
SetSubSeq ; ia a expr 8,6 
Shut., ae e i ak i expr 13.13 
Sin , e a ‘ expr 18.26 
ETDs w Se secs Be a Eh el eo ; expr 18.27 
Size. . . A EA š expr 8.5 
Spaces. ... A A expr 13.16 
SPECIALCLOSEFUNCTION!*. è global 13.3, 13.4 
SPECIALRDSACTION!*. .. é global 13.4 
SPECIALREADFUNCTION!* , 4 global 13.3, 13.5 
SPECIALWRITEFUNCTION! *, . global 13.3, 13.5 
SPECIALWRSACTION!#. .. á global 13.4, 13.5 
DOF. de aa da Ss : expr 18.29 
Standard!=CharP ih, e A expr 8.7 
StandardLisp. . . . è expr 14.4 
StartFork . ar hi 6 expr 20.4 
SIDENES e e ee : global 13.2, 13.3, 13.4 
STDOUT! War e te ee è . global 13.2, 13.3, 13.4 
StdTracês ace o as a a a e exp 16.8 
SUE cat wae a a Be Ee è expr 16.3 
SIOP e osie anana e a : edit 17.24 
Str2Iint sos e a % a expr 20.8 
SET e or O Se A a a ; expr 23.11 
String!-Capitalize. . . 3 expr 8.12 
String!-CharP ..... x expr 8.7 
String!-DownCase. . . . š expr 8.11 
String!-Equal . .. . . `. expr 8.10 
String!-GreaterP. . . + > expr 8.10 
String!-Left!-Trim. . . : expr 8.11 
String!-Length. .... ‘ expr 8.12 
String!-LessP ..... + > expr 8.10 
String!-Not!-Equal. ‘ > expr 8.11 
String!-Not!-GreaterP A ‘ expr 8.10 
String!-Not!-LessP. . . ó expr 8.10 
String!-Repeat. .... P expr 8.11 
String!-Right!-Trim . . i expr 8.11 
String!-to!-List. . . . è expr 8.12 
String!-to!-Vector. . . ‘ expr 8.12 
String! =Trit. . . 5... A expr 8.11 
String!-UpCase. . . . + > expr 8.11 
String!<!=. . e e eœ E expr 8.10 
String!<!>. saca eo : expr 8.10 
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